feat: add X-Logfire-Telemetry header

logfire/_internal/cli/__init__.py

@@ -22,7 +22,7 @@
 
 from ...version import VERSION
 from ..auth import HOME_LOGFIRE
-from ..client import LogfireClient
+from ..client import UA_HEADER, LogfireClient
 from ..config import REGIONS, LogfireCredentials, get_base_url_from_token
 from ..config_params import ParamManager
 from ..server_response import install_logfire_response_hook
@@ -448,6 +448,7 @@ def log_trace_id(response: requests.Response, context: ContextCarrier, *args: An
             context = get_context()
             session.hooks = {'response': [functools.partial(log_trace_id, context=context)]}
             session.headers.update(context)
+            session.headers['User-Agent'] = UA_HEADER
             install_logfire_response_hook(session)
             namespace._session = session
             namespace.func(namespace)

logfire/_internal/client.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import platform
 from typing import Any
 from urllib.parse import urljoin
 
@@ -13,7 +14,11 @@
 from .server_response import ServerResponseCallback, install_logfire_response_hook
 from .utils import UnexpectedResponse
 
-UA_HEADER = f'logfire/{VERSION}'
+UA_HEADER = (
+    f'logfire-sdk-python/{VERSION} '
+    f'({platform.python_implementation()} {platform.python_version()}, '
+    f'os {platform.platform()}, arch {platform.machine()})'
+)
 
 
 class ProjectAlreadyExists(Exception):
@@ -44,7 +49,12 @@ def __init__(
         self.base_url = user_token.base_url
         self._token = user_token.token
         self._session = Session()
-        self._session.headers.update({'Authorization': self._token, 'User-Agent': UA_HEADER})
+        self._session.headers.update(
+            {
+                'Authorization': self._token,
+                'User-Agent': UA_HEADER,
+            }
+        )
         install_logfire_response_hook(self._session, server_response_hook)
 
     @classmethod

logfire/_internal/config.py

@@ -71,7 +71,7 @@
 
 from ..propagate import NoExtractTraceContextPropagator, WarnOnExtractTraceContextPropagator
 from ..types import ExceptionCallback
-from .client import InvalidProjectName, LogfireClient, ProjectAlreadyExists
+from .client import UA_HEADER, InvalidProjectName, LogfireClient, ProjectAlreadyExists
 from .config_params import ParamManager, PydanticPluginRecordValues, normalize_token
 from .constants import (
     ATTRIBUTES_CONFIG,
@@ -112,6 +112,7 @@
 from .scrubbing import NOOP_SCRUBBER, BaseScrubber, Scrubber, ScrubbingOptions
 from .server_response import ServerResponseCallback, install_logfire_response_hook
 from .stack_info import warn_at_user_stacklevel
+from .telemetry_header import TELEMETRY_HEADER_NAME, build_telemetry_header
 from .tracer import OPEN_SPANS, PendingSpanProcessor, ProxyTracerProvider
 from .utils import (
     SeededRandomIdGenerator,
@@ -131,7 +132,7 @@
 
 CREDENTIALS_FILENAME = 'logfire_credentials.json'
 """Default base URL for the Logfire API."""
-COMMON_REQUEST_HEADERS = {'User-Agent': f'logfire/{VERSION}'}
+COMMON_REQUEST_HEADERS = {'User-Agent': UA_HEADER}
 """Common request headers for requests to the Logfire API."""
 PROJECT_NAME_PATTERN = r'^[a-z0-9]+(?:-[a-z0-9]+)*$'
 
@@ -935,6 +936,9 @@ def __init__(
         # This ensures that we only call OTEL's global set_tracer_provider once to avoid warnings.
         self._has_set_providers = False
         self._initialized = False
+        # Resolved in `_initialize` once the resource (and therefore its `service.instance.id`)
+        # exists; until then there is no value to advertise to the backend.
+        self._service_instance_id: str = ''
         self._lock = RLock()
 
     def configure(
@@ -1042,6 +1046,9 @@ def _initialize(self) -> None:
             # https://github.com/open-telemetry/semantic-conventions/blob/e44693245eef815071402b88c3a44a8f7f8f24c8/docs/resource/README.md#service-experimental
             # Both recommend generating a UUID.
             resource = Resource({'service.instance.id': uuid4().hex}).merge(resource)
+            # Cache the resolved service.instance.id so the X-Logfire-Telemetry header
+            # advertises the same UUID the OTLP resource attributes carry.
+            self._service_instance_id = str(resource.attributes.get('service.instance.id', ''))
 
             head = self.sampling.head
             sampler: Sampler | None = None
@@ -1171,9 +1178,15 @@ def check_tokens():
                         thread.start()
 
                     # Create exporters for each token
+                    telemetry_header_value = build_telemetry_header(self)
                     for token in token_list:
                         base_url = self.advanced.generate_base_url(token)
-                        headers = {'User-Agent': f'logfire/{VERSION}', 'Authorization': token}
+                        headers: dict[str, str] = {
+                            'User-Agent': UA_HEADER,
+                            'Authorization': token,
+                        }
+                        if telemetry_header_value is not None:
+                            headers[TELEMETRY_HEADER_NAME] = telemetry_header_value
                         session = OTLPExporterHttpSession()
                         install_logfire_response_hook(session, self.advanced.server_response_hook)
                         span_exporter = BodySizeCheckingOTLPSpanExporter(
@@ -1353,6 +1366,7 @@ def fix_pid():  # pragma: no cover
                     token=self.api_key,
                     options=self.variables,
                     server_response_hook=self.advanced.server_response_hook,
+                    telemetry_header=build_telemetry_header(self),
                 )
             multi_log_processor = SynchronousMultiLogRecordProcessor()
             for processor in log_record_processors:
@@ -1486,6 +1500,7 @@ def _lazy_init_variable_provider(self) -> VariableProvider:
                 token=api_key,
                 options=options,
                 server_response_hook=self.advanced.server_response_hook,
+                telemetry_header=build_telemetry_header(self),
             )
             self._variable_provider = provider
             provider.start(Logfire(config=self))
@@ -1504,7 +1519,12 @@ def warn_if_not_initialized(self, message: str):
     def _initialize_credentials_from_token(self, token: str) -> LogfireCredentials | None:
         session = requests.Session()
         install_logfire_response_hook(session, self.advanced.server_response_hook)
-        return LogfireCredentials.from_token(token, session, self.advanced.generate_base_url(token))
+        return LogfireCredentials.from_token(
+            token,
+            session,
+            self.advanced.generate_base_url(token),
+            telemetry_header=build_telemetry_header(self),
+        )
 
     def _ensure_flush_after_aws_lambda(self):
         """Ensure that `force_flush` is called after an AWS Lambda invocation.
@@ -1698,7 +1718,9 @@ def load_creds_file(cls, creds_dir: Path) -> Self | None:
                 raise LogfireConfigError(f'Invalid credentials file: {path} - {e}') from e
 
     @classmethod
-    def from_token(cls, token: str, session: requests.Session, base_url: str) -> Self | None:
+    def from_token(
+        cls, token: str, session: requests.Session, base_url: str, telemetry_header: str | None = None
+    ) -> Self | None:
         """Check that the token is valid.
 
         Issue a warning if the Logfire API is unreachable, or we get a response other than 200 or 401.
@@ -1708,11 +1730,14 @@ def from_token(cls, token: str, session: requests.Session, base_url: str) -> Sel
         Raises:
             LogfireConfigError: If the token is invalid.
         """
+        headers: dict[str, str] = {**COMMON_REQUEST_HEADERS, 'Authorization': token}
+        if telemetry_header is not None:
+            headers[TELEMETRY_HEADER_NAME] = telemetry_header
         try:
             response = session.get(
                 urljoin(base_url, '/v1/info'),
                 timeout=10,
-                headers={**COMMON_REQUEST_HEADERS, 'Authorization': token},
+                headers=headers,
             )
         except requests.RequestException as e:
             warnings.warn(f'Logfire API is unreachable, you may have trouble sending data. Error: {e}')

logfire/_internal/telemetry_header.py

@@ -0,0 +1,70 @@
+"""Build the `X-Logfire-Telemetry` request header.
+
+The header carries non-sensitive, config-derived signals about how this SDK
+instance is configured, encoded as a compact JSON object. SDK/runtime identity
+(version, language, Python version, OS, etc.) lives on the standard
+`User-Agent` header instead — see `UA_HEADER` in `_internal/client.py`.
+Secrets (`token`, `api_key`, `service_name`, etc.) are never included.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .config import LogfireConfig
+
+
+TELEMETRY_HEADER_NAME = 'X-Logfire-Telemetry'
+
+
+def _config_telemetry_pairs(config: LogfireConfig) -> dict[str, Any]:
+    """Pick fields of `LogfireConfig` that are useful for product analytics.
+
+    Each field below has an explicit rationale; do not add a field unless you have
+    one. Everything else either duplicates information the server already knows,
+    isn't actionable, or risks leaking sensitive data (token, api_key,
+    service_name, environment, etc.).
+    """
+    # Multi-project usage: how many users configure more than one write token in
+    # a single SDK instance. Drives auth/routing roadmap decisions.
+    token = config.token
+    if isinstance(token, list):
+        token_count = len(token)
+    elif token:
+        token_count = 1
+    else:
+        token_count = 0
+
+    pairs: dict[str, Any] = {
+        # Adoption signal for the `code_source=` option (newer feature): tells us
+        # whether the integration with the source-code link UI is worth investing in.
+        'code_source_set': config.code_source is not None,
+        # Adoption signal for the variables / feature-flag feature (newer feature):
+        # informs whether to keep building on it.
+        'variables_set': config.variables is not None,
+        'token_count': token_count,
+    }
+
+    if config._service_instance_id:  # pyright: ignore[reportPrivateUsage]
+        # Mirrors the OTLP resource attribute of the same name
+        # (https://opentelemetry.io/docs/specs/semconv/registry/attributes/service/#service-instance-id).
+        # High-cardinality per-process identifier — kept here rather than in
+        # User-Agent because user-agent strings are typically aggregated and a
+        # per-instance id would explode the cardinality of any UA-based analytics.
+        pairs['service_instance_id'] = config._service_instance_id  # pyright: ignore[reportPrivateUsage]
+
+    return pairs
+
+
+def build_telemetry_header(config: LogfireConfig | None = None) -> str | None:
+    """Return the JSON-encoded `X-Logfire-Telemetry` value, or None if no config.
+
+    Without a `LogfireConfig` there is nothing config-specific to report — the
+    SDK/runtime identity is already in `User-Agent`, so callers should simply
+    omit the header in that case.
+    """
+    if config is None:
+        return None
+    return json.dumps(_config_telemetry_pairs(config), separators=(',', ':'))

logfire/experimental/query_client.py

@@ -1,13 +1,12 @@
 from __future__ import annotations
 
-import platform
 from datetime import datetime
 from types import TracebackType
 from typing import TYPE_CHECKING, Any, Generic, Literal, TypedDict, TypeVar
 
 from typing_extensions import Self
 
-from logfire import VERSION
+from logfire._internal.client import UA_HEADER
 from logfire._internal.config import get_base_url_from_token
 
 try:
@@ -87,7 +86,6 @@ def _rows_to_columns(result: RowQueryResults) -> QueryResults:
 
 
 _ACCEPT = Literal['application/json', 'application/vnd.apache.arrow.stream', 'text/csv']
-_USER_AGENT = f'logfire-sdk-python/{VERSION} (Python {platform.python_version()}, os {platform.platform()}, arch {platform.machine()})'
 
 
 class _BaseLogfireQueryClient(Generic[T]):
@@ -97,7 +95,7 @@ def __init__(self, base_url: str, read_token: str, timeout: Timeout, client: typ
         self.timeout = timeout
         headers = client_kwargs.pop('headers', {})
         headers['authorization'] = read_token
-        headers.setdefault('user-agent', _USER_AGENT)
+        headers['user-agent'] = UA_HEADER
         self.client: T = client(timeout=timeout, base_url=base_url, headers=headers, **client_kwargs)
 
     def _build_query_params(

logfire/variables/remote.py

@@ -18,6 +18,7 @@
 from logfire._internal.client import UA_HEADER
 from logfire._internal.config import VariablesOptions
 from logfire._internal.server_response import ServerResponseCallback, install_logfire_response_hook
+from logfire._internal.telemetry_header import TELEMETRY_HEADER_NAME
 from logfire._internal.utils import UnexpectedResponse
 from logfire.variables.abstract import (
     ResolvedVariable,
@@ -61,6 +62,7 @@ def __init__(
         token: str,
         options: VariablesOptions,
         server_response_hook: ServerResponseCallback | None = None,
+        telemetry_header: str | None = None,
     ):
         """Create a new remote variable provider.
 
@@ -70,15 +72,22 @@ def __init__(
             options: Options for retrieving remote variables.
             server_response_hook: Optional override for the API response hook
                 (see `AdvancedOptions.server_response_hook`).
+            telemetry_header: Pre-built `X-Logfire-Telemetry` header value carrying the
+                SDK's config-derived signals (including `service.instance.id` so it
+                matches the OTLP resource attribute). When None, the header is omitted —
+                SDK/runtime identity is still sent on the standard `User-Agent` header.
         """
         block_before_first_resolve = options.block_before_first_resolve
         polling_interval = options.polling_interval
 
         self._base_url = base_url
         self._token = token
         self._server_response_hook = server_response_hook
+        self._telemetry_header = telemetry_header
         self._session = Session()
         self._session.headers.update({'Authorization': f'bearer {token}', 'User-Agent': UA_HEADER})
+        if self._telemetry_header is not None:
+            self._session.headers[TELEMETRY_HEADER_NAME] = self._telemetry_header
         install_logfire_response_hook(self._session, server_response_hook)
         self._timeout = options.timeout
         self._block_before_first_fetch = block_before_first_resolve
@@ -208,6 +217,8 @@ def _sse_listener(self):  # pragma: no cover
                             'Cache-Control': 'no-cache',
                         }
                     )
+                    if self._telemetry_header is not None:
+                        sse_session.headers[TELEMETRY_HEADER_NAME] = self._telemetry_header
                     install_logfire_response_hook(sse_session, self._server_response_hook)
 
                     # Open streaming connection