From b204ba43b3661f43a5d50f54de0aa826a41d1de7 Mon Sep 17 00:00:00 2001 From: Marcelo Trylesinski Date: Wed, 9 Oct 2024 11:37:59 +0200 Subject: [PATCH] Organize the documentation (#483) --- CHANGELOG.md | 1 + docs/api/integrations/logging.md | 1 - docs/api/integrations/structlog.md | 1 - docs/help.md | 2 +- docs/{ => reference}/api/exceptions.md | 0 docs/{ => reference}/api/logfire.md | 0 docs/{ => reference}/api/propagate.md | 0 .../api}/pydantic.md | 0 docs/{ => reference}/api/sampling.md | 0 docs/{ => reference}/api/testing.md | 0 docs/{ => reference}/examples.md | 12 ++++------- docs/reference/index.md | 6 ------ docs/roadmap.md | 3 +++ logfire-api/logfire_api/__init__.py | 7 ++++--- logfire-api/logfire_api/__init__.pyi | 10 +++++++++- logfire-api/logfire_api/_internal/config.pyi | 8 +++++++- logfire/__init__.py | 1 + logfire/integrations/loguru.py | 2 +- logfire/integrations/structlog.py | 2 +- mkdocs.yml | 20 ++++++++----------- tests/test_logfire_api.py | 4 ++++ 21 files changed, 44 insertions(+), 36 deletions(-) delete mode 100644 docs/api/integrations/logging.md delete mode 100644 docs/api/integrations/structlog.md rename docs/{ => reference}/api/exceptions.md (100%) rename docs/{ => reference}/api/logfire.md (100%) rename docs/{ => reference}/api/propagate.md (100%) rename docs/{api/integrations => reference/api}/pydantic.md (100%) rename docs/{ => reference}/api/sampling.md (100%) rename docs/{ => reference}/api/testing.md (100%) rename docs/{ => reference}/examples.md (70%) delete mode 100644 docs/reference/index.md diff --git a/CHANGELOG.md b/CHANGELOG.md index a7e5b229b..350ab61b9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -312,6 +312,7 @@ First release from new repo! [v0.53.0]: https://github.com/pydantic/logfire/compare/v0.52.0...v0.53.0 [v0.52.0]: https://github.com/pydantic/logfire/compare/v0.51.0...v0.52.0 [v0.51.0]: https://github.com/pydantic/logfire/compare/v0.50.1...v0.51.0 +[v0.50.1]: https://github.com/pydantic/logfire/compare/v0.50.0...v0.50.1 [v0.50.0]: https://github.com/pydantic/logfire/compare/v0.49.1...v0.50.0 [v0.49.1]: https://github.com/pydantic/logfire/compare/v0.49.0...v0.49.1 [v0.49.0]: https://github.com/pydantic/logfire/compare/v0.48.1...v0.49.0 diff --git a/docs/api/integrations/logging.md b/docs/api/integrations/logging.md deleted file mode 100644 index 4bb95219a..000000000 --- a/docs/api/integrations/logging.md +++ /dev/null @@ -1 +0,0 @@ -::: logfire.integrations.logging diff --git a/docs/api/integrations/structlog.md b/docs/api/integrations/structlog.md deleted file mode 100644 index 414a04145..000000000 --- a/docs/api/integrations/structlog.md +++ /dev/null @@ -1 +0,0 @@ -::: logfire.integrations.structlog diff --git a/docs/help.md b/docs/help.md index 941539095..02b5d4ee1 100644 --- a/docs/help.md +++ b/docs/help.md @@ -22,7 +22,7 @@ The [usage documentation](index.md) is the most complete guide on how to get sta ## :material-api: SDK API Documentation -The [SDK API documentation](api/logfire.md) give reference docs for the **Logfire** SDK. +The [SDK API documentation](reference/api/logfire.md) give reference docs for the **Logfire** SDK. ## :material-email: Email diff --git a/docs/api/exceptions.md b/docs/reference/api/exceptions.md similarity index 100% rename from docs/api/exceptions.md rename to docs/reference/api/exceptions.md diff --git a/docs/api/logfire.md b/docs/reference/api/logfire.md similarity index 100% rename from docs/api/logfire.md rename to docs/reference/api/logfire.md diff --git a/docs/api/propagate.md b/docs/reference/api/propagate.md similarity index 100% rename from docs/api/propagate.md rename to docs/reference/api/propagate.md diff --git a/docs/api/integrations/pydantic.md b/docs/reference/api/pydantic.md similarity index 100% rename from docs/api/integrations/pydantic.md rename to docs/reference/api/pydantic.md diff --git a/docs/api/sampling.md b/docs/reference/api/sampling.md similarity index 100% rename from docs/api/sampling.md rename to docs/reference/api/sampling.md diff --git a/docs/api/testing.md b/docs/reference/api/testing.md similarity index 100% rename from docs/api/testing.md rename to docs/reference/api/testing.md diff --git a/docs/examples.md b/docs/reference/examples.md similarity index 70% rename from docs/examples.md rename to docs/reference/examples.md index cc3489107..4622e1814 100644 --- a/docs/examples.md +++ b/docs/reference/examples.md @@ -1,28 +1,24 @@ ---- -hide: -- navigation ---- # Examples These are working, stand-alone apps and projects that you can clone, spin up locally and play around with to get a feel for the different capabilities of Logfire. **Got a suggestion?** -If you want to see an example of a particular language or library, [get in touch](help.md). +If you want to see an example of a particular language or library, [get in touch](../help.md). ## Python ### Flask and SQLAlchemy example -This example is a simple Python financial calculator app using Flask and SQLAlchemy which is instrumented using the appropriate integrations as well as [auto-tracing](guides/onboarding-checklist/add-auto-tracing.md). If you spin up the server locally and interact with the calculator app, you'll be able to see traces come in automatically: +This example is a simple Python financial calculator app using Flask and SQLAlchemy which is instrumented using the appropriate integrations as well as [auto-tracing](../guides/onboarding-checklist/add-auto-tracing.md). If you spin up the server locally and interact with the calculator app, you'll be able to see traces come in automatically: -![Flask and SQLAlchemy example](images/logfire-screenshot-examples-flask-sqlalchemy.png) +![Flask and SQLAlchemy example](../images/logfire-screenshot-examples-flask-sqlalchemy.png) [See it on GitHub :material-open-in-new:](https://github.com/pydantic/logfire/tree/main/examples/python/flask-sqlalchemy/){:target="_blank"} ## JavaScript -Currently we only have a Python SDK, but the Logfire backend and UI support data sent by any OpenTelemetry client. See the [alternative clients guide](guides/advanced/alternative-clients.md) for details on setting up OpenTelemetry in any language. We're working on a JavaScript SDK, but in the meantime here are some examples of using plain OpenTelemetry in JavaScript: +Currently we only have a Python SDK, but the Logfire backend and UI support data sent by any OpenTelemetry client. See the [alternative clients guide](../guides/advanced/alternative-clients.md) for details on setting up OpenTelemetry in any language. We're working on a JavaScript SDK, but in the meantime here are some examples of using plain OpenTelemetry in JavaScript: ### Cloudflare worker example diff --git a/docs/reference/index.md b/docs/reference/index.md deleted file mode 100644 index c5fc2d3ef..000000000 --- a/docs/reference/index.md +++ /dev/null @@ -1,6 +0,0 @@ -* **[Configuration](configuration.md):** -In this section we document the various ways you can configure which Logfire project your deployment will send data to. -* **[Organization Structure](organization-structure.md):** -In this section we document the organization, project, and permissions model in Logfire. -* **[SDK CLI docs](cli.md):** -Documentation of the `logfire` command-line interface. diff --git a/docs/roadmap.md b/docs/roadmap.md index ba90898b0..6ff3d2135 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -79,6 +79,9 @@ Logfire is built on top of OpenTelemetry, which means that it supports all the l Still, we are planning to create custom SDKs for JavaScript, TypeScript, and Rust, and make sure that the attributes are displayed in a nice way in the Logfire UI — as they are for Python. +For now, you can check our [Alternative Clients](guides/advanced/alternative-clients.md) section to see how +you can send data to Logfire from other languages. + See [this GitHub issue][language-support-gh-issue] for more information. ### Automatic anomaly detection diff --git a/logfire-api/logfire_api/__init__.py b/logfire-api/logfire_api/__init__.py index 5e7919d18..87f710d66 100644 --- a/logfire-api/logfire_api/__init__.py +++ b/logfire-api/logfire_api/__init__.py @@ -1,10 +1,9 @@ from __future__ import annotations -from contextlib import contextmanager import importlib import sys -from typing import TYPE_CHECKING, ContextManager, Literal -from contextlib import nullcontext +from contextlib import contextmanager, nullcontext +from typing import Any, ContextManager, Literal, TYPE_CHECKING from unittest.mock import MagicMock try: @@ -166,6 +165,8 @@ def shutdown(self, *args, **kwargs) -> None: ... instrument_system_metrics = DEFAULT_LOGFIRE_INSTANCE.instrument_system_metrics shutdown = DEFAULT_LOGFIRE_INSTANCE.shutdown + def loguru_handler() -> dict[str, Any]: ... + def no_auto_trace(x): return x diff --git a/logfire-api/logfire_api/__init__.pyi b/logfire-api/logfire_api/__init__.pyi index d7ffe5c1f..32403b2a3 100644 --- a/logfire-api/logfire_api/__init__.pyi +++ b/logfire-api/logfire_api/__init__.pyi @@ -10,8 +10,9 @@ from .integrations.logging import LogfireLoggingHandler as LogfireLoggingHandler from .integrations.structlog import LogfireProcessor as StructlogProcessor from .version import VERSION as VERSION from logfire.sampling import SamplingOptions as SamplingOptions +from typing import Any -__all__ = ['Logfire', 'LogfireSpan', 'LevelName', 'AdvancedOptions', 'ConsoleOptions', 'CodeSource', 'PydanticPlugin', 'configure', 'span', 'instrument', 'log', 'trace', 'debug', 'notice', 'info', 'warn', 'error', 'exception', 'fatal', 'force_flush', 'log_slow_async_callbacks', 'install_auto_tracing', 'instrument_pydantic', 'instrument_fastapi', 'instrument_openai', 'instrument_anthropic', 'instrument_asyncpg', 'instrument_httpx', 'instrument_celery', 'instrument_requests', 'instrument_psycopg', 'instrument_django', 'instrument_flask', 'instrument_starlette', 'instrument_aiohttp_client', 'instrument_sqlalchemy', 'instrument_redis', 'instrument_pymongo', 'instrument_mysql', 'instrument_system_metrics', 'AutoTraceModule', 'with_tags', 'with_settings', 'shutdown', 'load_spans_from_file', 'no_auto_trace', 'ScrubMatch', 'ScrubbingOptions', 'VERSION', 'suppress_instrumentation', 'StructlogProcessor', 'LogfireLoggingHandler', 'SamplingOptions', 'MetricsOptions'] +__all__ = ['Logfire', 'LogfireSpan', 'LevelName', 'AdvancedOptions', 'ConsoleOptions', 'CodeSource', 'PydanticPlugin', 'configure', 'span', 'instrument', 'log', 'trace', 'debug', 'notice', 'info', 'warn', 'error', 'exception', 'fatal', 'force_flush', 'log_slow_async_callbacks', 'install_auto_tracing', 'instrument_pydantic', 'instrument_fastapi', 'instrument_openai', 'instrument_anthropic', 'instrument_asyncpg', 'instrument_httpx', 'instrument_celery', 'instrument_requests', 'instrument_psycopg', 'instrument_django', 'instrument_flask', 'instrument_starlette', 'instrument_aiohttp_client', 'instrument_sqlalchemy', 'instrument_redis', 'instrument_pymongo', 'instrument_mysql', 'instrument_system_metrics', 'AutoTraceModule', 'with_tags', 'with_settings', 'shutdown', 'load_spans_from_file', 'no_auto_trace', 'ScrubMatch', 'ScrubbingOptions', 'VERSION', 'suppress_instrumentation', 'StructlogProcessor', 'LogfireLoggingHandler', 'loguru_handler', 'SamplingOptions', 'MetricsOptions'] DEFAULT_LOGFIRE_INSTANCE = Logfire() span = DEFAULT_LOGFIRE_INSTANCE.span @@ -49,4 +50,11 @@ warn = DEFAULT_LOGFIRE_INSTANCE.warn error = DEFAULT_LOGFIRE_INSTANCE.error fatal = DEFAULT_LOGFIRE_INSTANCE.fatal exception = DEFAULT_LOGFIRE_INSTANCE.exception + +def loguru_handler() -> dict[str, Any]: + """Create a **Logfire** handler for Loguru. + + Returns: + A dictionary with the handler and format for Loguru. + """ __version__ = VERSION diff --git a/logfire-api/logfire_api/_internal/config.pyi b/logfire-api/logfire_api/_internal/config.pyi index 41b3cf693..da6253be0 100644 --- a/logfire-api/logfire_api/_internal/config.pyi +++ b/logfire-api/logfire_api/_internal/config.pyi @@ -77,7 +77,11 @@ class MetricsOptions: @dataclass class CodeSource: - """Settings for the source code of the project.""" + """Settings for the source code of the project. + + !!! Warning + This setting is experimental, and may change in the future! + """ repository: str revision: str root_path: str @@ -111,6 +115,8 @@ def configure(*, send_to_logfire: bool | Literal['if-token-present'] | None = No Defaults to `True` if and only if the Python version is at least 3.11. sampling: Sampling options. See the [sampling guide](https://logfire.pydantic.dev/docs/guides/advanced/sampling/). code_source: Settings for the source code of the project. + !!! Warning + This setting is experimental, and may change in the future! advanced: Advanced options primarily used for testing by Logfire developers. """ diff --git a/logfire/__init__.py b/logfire/__init__.py index 7a780d83d..f2e5906fd 100644 --- a/logfire/__init__.py +++ b/logfire/__init__.py @@ -142,6 +142,7 @@ def loguru_handler() -> dict[str, Any]: 'suppress_instrumentation', 'StructlogProcessor', 'LogfireLoggingHandler', + 'loguru_handler', 'SamplingOptions', 'MetricsOptions', ) diff --git a/logfire/integrations/loguru.py b/logfire/integrations/loguru.py index e2850f486..5742478ca 100644 --- a/logfire/integrations/loguru.py +++ b/logfire/integrations/loguru.py @@ -1,4 +1,4 @@ -"""Integration with Loguru.""" +"""Integration with [Loguru](https://github.com/Delgan/loguru).""" from __future__ import annotations diff --git a/logfire/integrations/structlog.py b/logfire/integrations/structlog.py index 254d94956..7379723f9 100644 --- a/logfire/integrations/structlog.py +++ b/logfire/integrations/structlog.py @@ -1,4 +1,4 @@ -"""Logfire processor for structlog.""" +"""Logfire processor for [structlog](https://www.structlog.org/en/stable/).""" from __future__ import annotations diff --git a/mkdocs.yml b/mkdocs.yml index 1d0f5a8e6..83ff4d5f3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -138,21 +138,17 @@ nav: - Use Cases: - Web Frameworks: integrations/use-cases/web-frameworks.md - Reference: - - Reference: reference/index.md + - Examples: reference/examples.md - Configuration: reference/configuration.md - Organization Structure: reference/organization-structure.md - SDK CLI: reference/cli.md - - SDK API: - - Logfire: api/logfire.md - - Testing: api/testing.md - - Sampling: api/sampling.md - - Propagate: api/propagate.md - - Exceptions: api/exceptions.md - - Integrations: - - api/integrations/pydantic.md - - api/integrations/logging.md - - api/integrations/structlog.md - - Examples: examples.md + - SDK API: + - Logfire: reference/api/logfire.md + - Testing: reference/api/testing.md + - Sampling: reference/api/sampling.md + - Propagate: reference/api/propagate.md + - Exceptions: reference/api/exceptions.md + - Pydantic: reference/api/pydantic.md - Help: help.md - Roadmap: roadmap.md - Legal: diff --git a/tests/test_logfire_api.py b/tests/test_logfire_api.py index d653bb676..94e4882b6 100644 --- a/tests/test_logfire_api.py +++ b/tests/test_logfire_api.py @@ -152,6 +152,10 @@ def func() -> None: ... logfire_api.LogfireLoggingHandler() logfire__all__.remove('LogfireLoggingHandler') + assert hasattr(logfire_api, 'loguru_handler') + logfire_api.loguru_handler() + logfire__all__.remove('loguru_handler') + assert hasattr(logfire_api, 'StructlogProcessor') logfire_api.StructlogProcessor() logfire__all__.remove('StructlogProcessor')