Add logfire.configure(environment=...) (#557)

Co-authored-by: Alex Hall <alex.mojaki@gmail.com>
pydantic · Oct 30, 2024 · 74d1e39 · 74d1e39
1 parent 5480347
commit 74d1e39
Show file tree

Hide file tree

Showing 10 changed files with 140 additions and 35 deletions.
diff --git a/logfire-api/logfire_api/_internal/config.pyi b/logfire-api/logfire_api/_internal/config.pyi
@@ -2,7 +2,7 @@ import dataclasses
 import requests
 from .auth import DEFAULT_FILE as DEFAULT_FILE, DefaultFile as DefaultFile, is_logged_in as is_logged_in
 from .config_params import ParamManager as ParamManager, PydanticPluginRecordValues as PydanticPluginRecordValues
-from .constants import DEFAULT_FALLBACK_FILE_NAME as DEFAULT_FALLBACK_FILE_NAME, LevelName as LevelName, OTLP_MAX_BODY_SIZE as OTLP_MAX_BODY_SIZE, RESOURCE_ATTRIBUTES_CODE_ROOT_PATH as RESOURCE_ATTRIBUTES_CODE_ROOT_PATH, RESOURCE_ATTRIBUTES_VCS_REPOSITORY_REF_REVISION as RESOURCE_ATTRIBUTES_VCS_REPOSITORY_REF_REVISION, RESOURCE_ATTRIBUTES_VCS_REPOSITORY_URL as RESOURCE_ATTRIBUTES_VCS_REPOSITORY_URL
+from .constants import DEFAULT_FALLBACK_FILE_NAME as DEFAULT_FALLBACK_FILE_NAME, LevelName as LevelName, OTLP_MAX_BODY_SIZE as OTLP_MAX_BODY_SIZE, RESOURCE_ATTRIBUTES_CODE_ROOT_PATH as RESOURCE_ATTRIBUTES_CODE_ROOT_PATH, RESOURCE_ATTRIBUTES_DEPLOYMENT_ENVIRONMENT_NAME as RESOURCE_ATTRIBUTES_DEPLOYMENT_ENVIRONMENT_NAME, RESOURCE_ATTRIBUTES_VCS_REPOSITORY_REF_REVISION as RESOURCE_ATTRIBUTES_VCS_REPOSITORY_REF_REVISION, RESOURCE_ATTRIBUTES_VCS_REPOSITORY_URL as RESOURCE_ATTRIBUTES_VCS_REPOSITORY_URL
 from .exporters.console import ConsoleColorsValues as ConsoleColorsValues, IndentedConsoleSpanExporter as IndentedConsoleSpanExporter, ShowParentsConsoleSpanExporter as ShowParentsConsoleSpanExporter, SimpleConsoleSpanExporter as SimpleConsoleSpanExporter
 from .exporters.fallback import FallbackSpanExporter as FallbackSpanExporter
 from .exporters.file import FileSpanExporter as FileSpanExporter
@@ -84,28 +84,46 @@ class CodeSource:
     """
     repository: str
     revision: str
-    root_path: str
+    root_path: str = ...
 
 class DeprecatedKwargs(TypedDict): ...
 
-def configure(*, local: bool = False, send_to_logfire: bool | Literal['if-token-present'] | None = None, token: str | None = None, service_name: str | None = None, service_version: str | None = None, console: ConsoleOptions | Literal[False] | None = None, config_dir: Path | str | None = None, data_dir: Path | str | None = None, additional_span_processors: Sequence[SpanProcessor] | None = None, metrics: MetricsOptions | Literal[False] | None = None, scrubbing: ScrubbingOptions | Literal[False] | None = None, inspect_arguments: bool | None = None, sampling: SamplingOptions | None = None, code_source: CodeSource | None = None, advanced: AdvancedOptions | None = None, **deprecated_kwargs: Unpack[DeprecatedKwargs]) -> Logfire:
+def configure(*, local: bool = False, send_to_logfire: bool | Literal['if-token-present'] | None = None, token: str | None = None, service_name: str | None = None, service_version: str | None = None, environment: str | None = None, console: ConsoleOptions | Literal[False] | None = None, config_dir: Path | str | None = None, data_dir: Path | str | None = None, additional_span_processors: Sequence[SpanProcessor] | None = None, metrics: MetricsOptions | Literal[False] | None = None, scrubbing: ScrubbingOptions | Literal[False] | None = None, inspect_arguments: bool | None = None, sampling: SamplingOptions | None = None, code_source: CodeSource | None = None, advanced: AdvancedOptions | None = None, **deprecated_kwargs: Unpack[DeprecatedKwargs]) -> Logfire:
     """Configure the logfire SDK.
 
     Args:
         local: If `True`, configures and returns a `Logfire` instance that is not the default global instance.
             Use this to create multiple separate configurations, e.g. to send to different projects.
-        send_to_logfire: Whether to send logs to logfire.dev. Defaults to the `LOGFIRE_SEND_TO_LOGFIRE` environment
-            variable if set, otherwise defaults to `True`. If `if-token-present` is provided, logs will only be sent if
-            a token is present.
-        token: The project token. Defaults to the `LOGFIRE_TOKEN` environment variable.
-        service_name: Name of this service. Defaults to the `LOGFIRE_SERVICE_NAME` environment variable.
-        service_version: Version of this service. Defaults to the `LOGFIRE_SERVICE_VERSION` environment variable, or the
-            current git commit hash if available.
+        send_to_logfire: Whether to send logs to logfire.dev.
+
+            Defaults to the `LOGFIRE_SEND_TO_LOGFIRE` environment variable if set, otherwise defaults to `True`.
+            If `if-token-present` is provided, logs will only be sent if a token is present.
+
+        token: The project token.
+
+            Defaults to the `LOGFIRE_TOKEN` environment variable.
+
+        service_name: Name of this service.
+
+            Defaults to the `LOGFIRE_SERVICE_NAME` environment variable.
+
+        service_version: Version of this service.
+
+            Defaults to the `LOGFIRE_SERVICE_VERSION` environment variable, or the current git commit hash if available.
+
+        environment: The environment this service is running in, e.g. `'staging'` or `'prod'`. Sets the
+            [`deployment.environment.name`](https://opentelemetry.io/docs/specs/semconv/resource/deployment-environment/)
+            resource attribute. Useful for filtering within projects in the Logfire UI.
+
+            Defaults to the `LOGFIRE_ENVIRONMENT` environment variable.
+
         console: Whether to control terminal output. If `None` uses the `LOGFIRE_CONSOLE_*` environment variables,
             otherwise defaults to `ConsoleOption(colors='auto', indent_spans=True, include_timestamps=True, verbose=False)`.
             If `False` disables console output. It can also be disabled by setting `LOGFIRE_CONSOLE` environment variable to `false`.
+
         config_dir: Directory that contains the `pyproject.toml` file for this project. If `None` uses the
             `LOGFIRE_CONFIG_DIR` environment variable, otherwise defaults to the current working directory.
+
         data_dir: Directory to store credentials, and logs. If `None` uses the `LOGFIRE_CREDENTIALS_DIR` environment variable, otherwise defaults to `'.logfire'`.
         additional_span_processors: Span processors to use in addition to the default processor which exports spans to Logfire's API.
         metrics: Set to `False` to disable sending all metrics,
@@ -114,7 +132,9 @@ def configure(*, local: bool = False, send_to_logfire: bool | Literal['if-token-
         inspect_arguments: Whether to enable
             [f-string magic](https://logfire.pydantic.dev/docs/guides/onboarding-checklist/add-manual-tracing/#f-strings).
             If `None` uses the `LOGFIRE_INSPECT_ARGUMENTS` environment variable.
+
             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
@@ -137,6 +157,7 @@ class _LogfireConfigData:
     token: str | None
     service_name: str
     service_version: str | None
+    environment: str | None
     console: ConsoleOptions | Literal[False] | None
     data_dir: Path
     additional_span_processors: Sequence[SpanProcessor] | None
@@ -147,14 +168,14 @@ class _LogfireConfigData:
     advanced: AdvancedOptions
 
 class LogfireConfig(_LogfireConfigData):
-    def __init__(self, send_to_logfire: bool | Literal['if-token-present'] | None = None, token: str | None = None, service_name: str | None = None, service_version: str | None = None, console: ConsoleOptions | Literal[False] | None = None, config_dir: Path | None = None, data_dir: Path | None = None, additional_span_processors: Sequence[SpanProcessor] | None = None, metrics: MetricsOptions | Literal[False] | None = None, scrubbing: ScrubbingOptions | Literal[False] | None = None, inspect_arguments: bool | None = None, sampling: SamplingOptions | None = None, code_source: CodeSource | None = None, advanced: AdvancedOptions | None = None) -> None:
+    def __init__(self, send_to_logfire: bool | Literal['if-token-present'] | None = None, token: str | None = None, service_name: str | None = None, service_version: str | None = None, environment: str | None = None, console: ConsoleOptions | Literal[False] | None = None, config_dir: Path | None = None, data_dir: Path | None = None, additional_span_processors: Sequence[SpanProcessor] | None = None, metrics: MetricsOptions | Literal[False] | None = None, scrubbing: ScrubbingOptions | Literal[False] | None = None, inspect_arguments: bool | None = None, sampling: SamplingOptions | None = None, code_source: CodeSource | None = None, advanced: AdvancedOptions | None = None) -> None:
         """Create a new LogfireConfig.
 
         Users should never need to call this directly, instead use `logfire.configure`.
 
         See `_LogfireConfigData` for parameter documentation.
         """
-    def configure(self, send_to_logfire: bool | Literal['if-token-present'] | None, token: str | None, service_name: str | None, service_version: str | None, console: ConsoleOptions | Literal[False] | None, config_dir: Path | None, data_dir: Path | None, additional_span_processors: Sequence[SpanProcessor] | None, metrics: MetricsOptions | Literal[False] | None, scrubbing: ScrubbingOptions | Literal[False] | None, inspect_arguments: bool | None, sampling: SamplingOptions | None, code_source: CodeSource | None, advanced: AdvancedOptions | None) -> None: ...
+    def configure(self, send_to_logfire: bool | Literal['if-token-present'] | None, token: str | None, service_name: str | None, service_version: str | None, environment: str | None, console: ConsoleOptions | Literal[False] | None, config_dir: Path | None, data_dir: Path | None, additional_span_processors: Sequence[SpanProcessor] | None, metrics: MetricsOptions | Literal[False] | None, scrubbing: ScrubbingOptions | Literal[False] | None, inspect_arguments: bool | None, sampling: SamplingOptions | None, code_source: CodeSource | None, advanced: AdvancedOptions | None) -> None: ...
     def initialize(self) -> None:
         """Configure internals to start exporting traces and metrics."""
     def force_flush(self, timeout_millis: int = 30000) -> bool:

diff --git a/logfire-api/logfire_api/_internal/config_params.pyi b/logfire-api/logfire_api/_internal/config_params.pyi
@@ -33,6 +33,7 @@ SEND_TO_LOGFIRE: Incomplete
 TOKEN: Incomplete
 SERVICE_NAME: Incomplete
 SERVICE_VERSION: Incomplete
+ENVIRONMENT: Incomplete
 CREDENTIALS_DIR: Incomplete
 CONSOLE: Incomplete
 CONSOLE_COLORS: Incomplete

diff --git a/logfire-api/logfire_api/_internal/constants.pyi b/logfire-api/logfire_api/_internal/constants.pyi
@@ -27,9 +27,11 @@ NULL_ARGS_KEY: str
 PENDING_SPAN_NAME_SUFFIX: str
 LOGFIRE_BASE_URL: str
 RESOURCE_ATTRIBUTES_PACKAGE_VERSIONS: str
+RESOURCE_ATTRIBUTES_DEPLOYMENT_ENVIRONMENT_NAME: str
 RESOURCE_ATTRIBUTES_VCS_REPOSITORY_REF_REVISION: str
 RESOURCE_ATTRIBUTES_VCS_REPOSITORY_URL: str
 RESOURCE_ATTRIBUTES_CODE_ROOT_PATH: str
+RESOURCE_ATTRIBUTES_CODE_WORK_DIR: str
 OTLP_MAX_INT_SIZE: Incomplete
 DEFAULT_FALLBACK_FILE_NAME: str
 ATTRIBUTES_SAMPLE_RATE_KEY: str

diff --git a/logfire-api/logfire_api/_internal/main.pyi b/logfire-api/logfire_api/_internal/main.pyi
@@ -415,7 +415,8 @@ class Logfire:
                 matches any of the regexes. This applies to both the Logfire and OpenTelemetry instrumentation.
                 If not provided, the environment variables
                 `OTEL_PYTHON_FASTAPI_EXCLUDED_URLS` and `OTEL_PYTHON_EXCLUDED_URLS` will be checked.
-            record_send_receive: Set to True to allow the OpenTelemetry ASGI to create send/receive spans.
+            record_send_receive: Set to `True` to allow the OpenTelemetry ASGI middleware to create send/receive spans.
+
                 These are disabled by default to reduce overhead and the number of spans created,
                 since many can be created for a single request, and they are not often useful.
                 If enabled, they will be set to debug level, meaning they will usually still be hidden in the UI.
@@ -622,7 +623,7 @@ class Logfire:
         Args:
             app: The Starlette app to instrument.
             capture_headers: Set to `True` to capture all request and response headers.
-            record_send_receive: Set `record_send_receive` to `True` to allow the OpenTelemetry ASGI to create send/receive spans.
+            record_send_receive: Set to `True` to allow the OpenTelemetry ASGI middleware to create send/receive spans.
 
                 These are disabled by default to reduce overhead and the number of spans created,
                 since many can be created for a single request, and they are not often useful.
@@ -641,7 +642,8 @@ class Logfire:
         Args:
             app: The ASGI application to instrument.
             capture_headers: Set to `True` to capture all request and response headers.
-            record_send_receive: Set to `True` to allow the OpenTelemetry ASGI to create send/receive spans.
+            record_send_receive: Set to `True` to allow the OpenTelemetry ASGI middleware to create send/receive spans.
+
                 These are disabled by default to reduce overhead and the number of spans created,
                 since many can be created for a single request, and they are not often useful.
                 If enabled, they will be set to debug level, meaning they will usually still be hidden in the UI.

diff --git a/logfire-api/logfire_api/integrations/logging.pyi b/logfire-api/logfire_api/integrations/logging.pyi
@@ -8,7 +8,7 @@ from typing import Any, ClassVar
 RESERVED_ATTRS: frozenset[str]
 
 class LogfireLoggingHandler(LoggingHandler):
-    """A logging handler that sends logs to **Logfire**."""
+    """A [logging](../../integrations/logging.md) handler that sends logs to **Logfire**."""
     custom_scope_suffix: ClassVar[str]
     fallback: Incomplete
     logfire_instance: Incomplete

diff --git a/logfire-api/logfire_api/integrations/structlog.pyi b/logfire-api/logfire_api/integrations/structlog.pyi
@@ -6,7 +6,7 @@ from structlog.types import EventDict, WrappedLogger
 RESERVED_ATTRS: Incomplete
 
 class LogfireProcessor:
-    """Logfire processor for structlog."""
+    """Logfire processor for [structlog](../../integrations/structlog.md)."""
     console_log: Incomplete
     logfire_instance: Incomplete
     def __init__(self, *, console_log: bool = False, logfire_instance: Logfire | None = None) -> None: ...