flagsmith-common 3.4.0__tar.gz → 3.6.0__tar.gz

{flagsmith_common-3.4.0 → flagsmith_common-3.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flagsmith-common
-Version: 3.4.0
+Version: 3.6.0
 Summary: Flagsmith's common library
 Author: Matthew Elwell, Gagan Trivedi, Kim Gustyr, Zach Aysan, Francesco Lo Franco, Rodrigo López Dato, Evandro Myller, Wadii Zaim
 License-Expression: BSD-3-Clause
@@ -17,10 +17,21 @@ Requires-Dist: drf-spectacular>=0.28.0,<1 ; extra == 'common-core'
 Requires-Dist: drf-writable-nested ; extra == 'common-core'
 Requires-Dist: environs<15 ; extra == 'common-core'
 Requires-Dist: gunicorn>=19.1 ; extra == 'common-core'
+Requires-Dist: inflection ; extra == 'common-core'
+Requires-Dist: opentelemetry-api>=1.25,<2 ; extra == 'common-core'
+Requires-Dist: opentelemetry-sdk>=1.25,<2 ; extra == 'common-core'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.25,<2 ; extra == 'common-core'
+Requires-Dist: opentelemetry-instrumentation-django>=0.46b0,<1 ; extra == 'common-core'
+Requires-Dist: opentelemetry-instrumentation-psycopg2>=0.46b0,<1 ; extra == 'common-core'
+Requires-Dist: opentelemetry-instrumentation-redis>=0.46b0,<1 ; extra == 'common-core'
+Requires-Dist: redis>=5,<6 ; extra == 'common-core'
 Requires-Dist: prometheus-client>=0.0.16 ; extra == 'common-core'
 Requires-Dist: psycopg2-binary>=2.9,<3 ; extra == 'common-core'
 Requires-Dist: requests ; extra == 'common-core'
+Requires-Dist: sentry-sdk>=2.0.0,<3.0.0 ; extra == 'common-core'
 Requires-Dist: simplejson>=3,<4 ; extra == 'common-core'
+Requires-Dist: structlog>=24.4,<26 ; extra == 'common-core'
+Requires-Dist: typing-extensions ; extra == 'common-core'
 Requires-Dist: simplejson ; extra == 'flagsmith-schemas'
 Requires-Dist: typing-extensions ; extra == 'flagsmith-schemas'
 Requires-Dist: flagsmith-flag-engine>6 ; extra == 'flagsmith-schemas'
@@ -142,6 +153,54 @@ Use this mark to auto-use the `saas_mode` fixture.
 
 Use this mark to auto-use the `enterprise_mode` fixture.
 
+### OpenTelemetry
+
+Flagsmith supports exporting traces and structured logs over OTLP.
+
+#### Configuration
+
+OTel instrumentation is opt-in, controlled by environment variables:
+
+| Variable                          | Description                                                                                                           | Default         |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------- |
+| `OTEL_EXPORTER_OTLP_ENDPOINT`     | Base OTLP endpoint (e.g. `http://collector:4318`). If unset, no OTel setup occurs.                                    | _(disabled)_    |
+| `OTEL_SERVICE_NAME`               | The `service.name` resource attribute.                                                                                | `flagsmith-api` |
+| `OTEL_TRACING_EXCLUDED_URL_PATHS` | Comma-separated URL paths to exclude from tracing (e.g. `health/liveness,health/readiness`).                          | _(none)_        |
+
+Standard `OTEL_*` env vars (e.g. `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_EXPORTER_OTLP_HEADERS`) are also respected by the OTel SDK.
+
+#### What gets configured
+
+When `OTEL_EXPORTER_OTLP_ENDPOINT` is set, `ensure_cli_env()` sets up:
+
+- **Tracing**: `TracerProvider` with OTLP/HTTP span export, W3C `TraceContext` + `Baggage` propagation, and auto-instrumentation for:
+  - **Django** (`DjangoInstrumentor`): creates a root span per HTTP request with span names formatted as `{METHOD} {route_template}` (e.g. `GET /api/v1/projects/{pk}/`).
+  - **psycopg2** (`Psycopg2Instrumentor`): creates child spans for each SQL query with `db.system`, `db.statement`, and `db.name` attributes. SQL commenter is enabled, adding trace context as SQL comments for database-side correlation.
+  - **Redis** (`RedisInstrumentor`): creates child spans for each Redis command with `db.system` and `db.statement` attributes.
+- **Structured log export**: A structlog processor that emits each log event as both an OTLP log record and a span event (when an active span exists).
+
+#### Emitting OTel log events via structlog
+
+Use structlog as usual. The OTel processor captures events and maps them to OTLP log records:
+
+```python
+import structlog
+
+log = structlog.get_logger("code_references")
+log.info("scan-created", code_references__count=3, feature__count=2)
+```
+
+This produces:
+
+1. An **OTLP log record** with:
+   - `Body: scan-created`
+   - `EventName: code_references.scan_created` (logger name + `inflection.underscore` of the event)
+   - `Severity: INFO`
+   - `Attributes: code_references.count=3, feature.count=2` (double underscores are converted to dots)
+   - W3C Baggage entries from the current OTel context are copied into log attributes (e.g. `amplitude.device_id`, `amplitude.session_id`).
+
+2. A **span event** on the active span (if one exists) with the same name and attributes. This makes structlog events visible in trace backends (e.g. SigNoz's "Events" tab) without requiring separate log correlation. When no span is active (e.g. during startup or management commands), only the OTLP log record is emitted.
+
 ### Metrics
 
 Flagsmith uses Prometheus to track performance metrics.

{flagsmith_common-3.4.0 → flagsmith_common-3.6.0}/README.md

@@ -96,6 +96,54 @@ Use this mark to auto-use the `saas_mode` fixture.
 
 Use this mark to auto-use the `enterprise_mode` fixture.
 
+### OpenTelemetry
+
+Flagsmith supports exporting traces and structured logs over OTLP.
+
+#### Configuration
+
+OTel instrumentation is opt-in, controlled by environment variables:
+
+| Variable                          | Description                                                                                                           | Default         |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------- |
+| `OTEL_EXPORTER_OTLP_ENDPOINT`     | Base OTLP endpoint (e.g. `http://collector:4318`). If unset, no OTel setup occurs.                                    | _(disabled)_    |
+| `OTEL_SERVICE_NAME`               | The `service.name` resource attribute.                                                                                | `flagsmith-api` |
+| `OTEL_TRACING_EXCLUDED_URL_PATHS` | Comma-separated URL paths to exclude from tracing (e.g. `health/liveness,health/readiness`).                          | _(none)_        |
+
+Standard `OTEL_*` env vars (e.g. `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_EXPORTER_OTLP_HEADERS`) are also respected by the OTel SDK.
+
+#### What gets configured
+
+When `OTEL_EXPORTER_OTLP_ENDPOINT` is set, `ensure_cli_env()` sets up:
+
+- **Tracing**: `TracerProvider` with OTLP/HTTP span export, W3C `TraceContext` + `Baggage` propagation, and auto-instrumentation for:
+  - **Django** (`DjangoInstrumentor`): creates a root span per HTTP request with span names formatted as `{METHOD} {route_template}` (e.g. `GET /api/v1/projects/{pk}/`).
+  - **psycopg2** (`Psycopg2Instrumentor`): creates child spans for each SQL query with `db.system`, `db.statement`, and `db.name` attributes. SQL commenter is enabled, adding trace context as SQL comments for database-side correlation.
+  - **Redis** (`RedisInstrumentor`): creates child spans for each Redis command with `db.system` and `db.statement` attributes.
+- **Structured log export**: A structlog processor that emits each log event as both an OTLP log record and a span event (when an active span exists).
+
+#### Emitting OTel log events via structlog
+
+Use structlog as usual. The OTel processor captures events and maps them to OTLP log records:
+
+```python
+import structlog
+
+log = structlog.get_logger("code_references")
+log.info("scan-created", code_references__count=3, feature__count=2)
+```
+
+This produces:
+
+1. An **OTLP log record** with:
+   - `Body: scan-created`
+   - `EventName: code_references.scan_created` (logger name + `inflection.underscore` of the event)
+   - `Severity: INFO`
+   - `Attributes: code_references.count=3, feature.count=2` (double underscores are converted to dots)
+   - W3C Baggage entries from the current OTel context are copied into log attributes (e.g. `amplitude.device_id`, `amplitude.session_id`).
+
+2. A **span event** on the active span (if one exists) with the same name and attributes. This makes structlog events visible in trace backends (e.g. SigNoz's "Events" tab) without requiring separate log correlation. When no span is active (e.g. during startup or management commands), only the OTLP log record is emitted.
+
 ### Metrics
 
 Flagsmith uses Prometheus to track performance metrics.

{flagsmith_common-3.4.0 → flagsmith_common-3.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flagsmith-common"
-version = "3.4.0"
+version = "3.6.0"
 description = "Flagsmith's common library"
 requires-python = ">=3.11,<4.0"
 dependencies = []
@@ -16,10 +16,21 @@ optional-dependencies = { test-tools = [
     "drf-writable-nested",
     "environs (<15)",
     "gunicorn (>=19.1)",
+    "inflection",
+    "opentelemetry-api (>=1.25,<2)",
+    "opentelemetry-sdk (>=1.25,<2)",
+    "opentelemetry-exporter-otlp-proto-http (>=1.25,<2)",
+    "opentelemetry-instrumentation-django (>=0.46b0,<1)",
+    "opentelemetry-instrumentation-psycopg2 (>=0.46b0,<1)",
+    "opentelemetry-instrumentation-redis (>=0.46b0,<1)",
+    "redis (>=5,<6)",
     "prometheus-client (>=0.0.16)",
     "psycopg2-binary (>=2.9,<3)",
     "requests",
+    "sentry-sdk (>=2.0.0,<3.0.0)",
     "simplejson (>=3,<4)",
+    "structlog (>=24.4,<26)",
+    "typing_extensions",
 ], task-processor = [
     "backoff (>=2.2.1,<3.0.0)",
     "django (>4,<6)",

{flagsmith_common-3.4.0 → flagsmith_common-3.6.0}/src/common/core/constants.py

@@ -1 +1,3 @@
 DEFAULT_PROMETHEUS_MULTIPROC_DIR_NAME = "flagsmith-prometheus"
+
+LOGGING_DEFAULT_ROOT_LOG_LEVEL = "WARNING"

flagsmith_common-3.6.0/src/common/core/logging.py

@@ -0,0 +1,186 @@
+import json
+import logging
+import logging.config
+import os
+import sys
+import threading
+from typing import Any
+
+import structlog
+import structlog.contextvars
+import structlog.dev
+import structlog.processors
+import structlog.stdlib
+from structlog.typing import EventDict, Processor, WrappedLogger
+from typing_extensions import TypedDict
+
+from common.core.constants import LOGGING_DEFAULT_ROOT_LOG_LEVEL
+from common.core.sentry import sentry_processor
+
+logger = logging.getLogger(__name__)
+
+
+class JsonRecord(TypedDict, extra_items=Any, total=False):  # type: ignore[call-arg]  # TODO https://github.com/python/mypy/issues/18176
+    levelname: str
+    message: str
+    timestamp: str
+    logger_name: str
+    pid: int | None
+    thread_name: str | None
+    exc_info: str
+
+
+def setup_logging(
+    log_level: str = "INFO",
+    log_format: str = "generic",
+    logging_configuration_file: str | None = None,
+    application_loggers: list[str] | None = None,
+    extra_foreign_processors: list[Processor] | None = None,
+    otel_processors: list[Processor] | None = None,
+) -> None:
+    """
+    Set up logging for the application.
+
+    This should be called early, before Django settings are loaded, to ensure
+    that all log output is properly formatted from the start.
+
+    Args:
+        log_level: The log level for application code (e.g. "DEBUG", "INFO").
+        log_format: Either "generic" or "json".
+        logging_configuration_file: Path to a JSON logging config file.
+            If provided, this takes precedence over other format options.
+        application_loggers: Top-level logger names for application packages.
+            These loggers are set to ``log_level`` while the root logger uses
+            ``max(log_level, WARNING)`` to suppress noise from third-party
+            libraries. If ``log_level`` is DEBUG, everything logs at DEBUG.
+        extra_foreign_processors: Additional structlog processors to run in
+            the ``foreign_pre_chain`` for stdlib log records (e.g. the
+            Gunicorn access log field extractor).
+    """
+    if logging_configuration_file:
+        with open(logging_configuration_file) as f:
+            config = json.load(f)
+        logging.config.dictConfig(config)
+    else:
+        log_level_int = logging.getLevelNamesMapping()[log_level.upper()]
+        root_level_int = logging.getLevelNamesMapping()[LOGGING_DEFAULT_ROOT_LOG_LEVEL]
+        # Suppress third-party noise at WARNING, but if the user requests
+        # DEBUG, honour that for the entire process.
+        effective_root_level = (
+            log_level_int if log_level_int < logging.INFO else root_level_int
+        )
+
+        dict_config: dict[str, Any] = {
+            "version": 1,
+            "disable_existing_loggers": False,
+            "handlers": {
+                "console": {
+                    "class": "logging.StreamHandler",
+                    "stream": "ext://sys.stdout",
+                    "level": log_level,
+                },
+            },
+            "root": {
+                "level": effective_root_level,
+                "handlers": ["console"],
+            },
+            "loggers": {
+                name: {"level": log_level, "handlers": [], "propagate": True}
+                for name in application_loggers or []
+            },
+        }
+        logging.config.dictConfig(dict_config)
+
+    setup_structlog(
+        log_format=log_format,
+        extra_foreign_processors=extra_foreign_processors,
+        otel_processors=otel_processors,
+    )
+
+
+def map_event_to_json_record(
+    logger: WrappedLogger,
+    method_name: str,
+    event_dict: EventDict,
+) -> EventDict:
+    """Map structlog fields to match :class:`JsonRecord` output schema."""
+    # Remove foreign record args injected by pass_foreign_args so they
+    # don't leak into the rendered JSON output.
+    event_dict.pop("positional_args", None)
+    record: JsonRecord = {
+        "message": event_dict.pop("event", ""),
+        "levelname": event_dict.pop("level", "").upper(),
+        "logger_name": event_dict.pop("logger", ""),
+        "pid": os.getpid(),
+        "thread_name": threading.current_thread().name,
+    }
+    if "exception" in event_dict:
+        record["exc_info"] = event_dict.pop("exception")
+    # Merge remaining structlog keys (e.g. extra_key from bind()) with the
+    # canonical record so they appear in the JSON output.
+    event_dict.update(record)
+    return event_dict
+
+
+def setup_structlog(
+    log_format: str,
+    extra_foreign_processors: list[Processor] | None = None,
+    otel_processors: list[Processor] | None = None,
+) -> None:
+    """Configure structlog to route through stdlib logging."""
+
+    if log_format == "json":
+        renderer_processors: list[Processor] = [
+            map_event_to_json_record,
+            structlog.processors.JSONRenderer(),
+        ]
+    else:
+        colors = sys.stdout.isatty() and structlog.dev._has_colors
+        renderer_processors = [
+            structlog.dev.ConsoleRenderer(colors=colors),
+        ]
+
+    foreign_pre_chain: list[Processor] = [
+        structlog.contextvars.merge_contextvars,
+        structlog.stdlib.add_logger_name,
+        structlog.stdlib.add_log_level,
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.processors.format_exc_info,
+        structlog.stdlib.ExtraAdder(),
+        *(extra_foreign_processors or []),
+    ]
+
+    formatter = structlog.stdlib.ProcessorFormatter(
+        processors=[
+            structlog.stdlib.ProcessorFormatter.remove_processors_meta,
+            *renderer_processors,
+        ],
+        foreign_pre_chain=foreign_pre_chain,
+        pass_foreign_args=True,
+    )
+
+    # Replace the formatter on existing root handlers with ProcessorFormatter.
+    root = logging.getLogger()
+    for handler in root.handlers:
+        handler.setFormatter(formatter)
+
+    structlog.configure(
+        processors=[
+            structlog.contextvars.merge_contextvars,
+            structlog.stdlib.filter_by_level,
+            structlog.stdlib.add_logger_name,
+            structlog.stdlib.add_log_level,
+            structlog.stdlib.PositionalArgumentsFormatter(),
+            structlog.processors.StackInfoRenderer(),
+            structlog.processors.UnicodeDecoder(),
+            structlog.processors.format_exc_info,
+            structlog.processors.TimeStamper(fmt="iso"),
+            sentry_processor,
+            *(otel_processors or []),
+            structlog.stdlib.ProcessorFormatter.wrap_for_formatter,
+        ],
+        wrapper_class=structlog.stdlib.BoundLogger,
+        context_class=dict,
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        cache_logger_on_first_use=True,
+    )

{flagsmith_common-3.4.0 → flagsmith_common-3.6.0}/src/common/core/main.py

@@ -8,8 +8,13 @@ from tempfile import mkdtemp
 from django.core.management import (
     execute_from_command_line as django_execute_from_command_line,
 )
+from environs import Env
 
 from common.core.cli import healthcheck
+from common.core.logging import setup_logging
+from common.gunicorn.processors import make_gunicorn_access_processor
+
+env = Env()
 
 logger = logging.getLogger(__name__)
 
@@ -32,7 +37,48 @@ def ensure_cli_env() -> typing.Generator[None, None, None]:
     """
     ctx = contextlib.ExitStack()
 
-    # TODO @khvn26 Move logging setup to here
+    # Set up OTel instrumentation (opt-in via OTEL_EXPORTER_OTLP_ENDPOINT).
+    otel_processors = None
+    otel_endpoint = env.str("OTEL_EXPORTER_OTLP_ENDPOINT", None)
+    if otel_endpoint:
+        from common.core.otel import (
+            add_otel_trace_context,
+            build_otel_log_provider,
+            build_tracer_provider,
+            make_structlog_otel_processor,
+            setup_tracing,
+        )
+
+        service_name = env.str("OTEL_SERVICE_NAME", "flagsmith-api")
+        log_provider = build_otel_log_provider(
+            endpoint=f"{otel_endpoint}/v1/logs",
+            service_name=service_name,
+        )
+        otel_processors = [
+            add_otel_trace_context,
+            make_structlog_otel_processor(log_provider),
+        ]
+        tracer_provider = build_tracer_provider(
+            endpoint=f"{otel_endpoint}/v1/traces",
+            service_name=service_name,
+        )
+        excluded_urls = env.str("OTEL_TRACING_EXCLUDED_URL_PATHS", None)
+        ctx.enter_context(setup_tracing(tracer_provider, excluded_urls=excluded_urls))
+        ctx.callback(log_provider.shutdown)
+
+    # Set up logging early, before Django settings are loaded.
+    setup_logging(
+        log_level=env.str("LOG_LEVEL", "INFO"),
+        log_format=env.str("LOG_FORMAT", "generic"),
+        logging_configuration_file=env.str("LOGGING_CONFIGURATION_FILE", None),
+        application_loggers=env.list("APPLICATION_LOGGERS", []) or None,
+        extra_foreign_processors=[
+            make_gunicorn_access_processor(
+                env.list("ACCESS_LOG_EXTRA_ITEMS", []) or None,
+            ),
+        ],
+        otel_processors=otel_processors,
+    )
 
     # Prometheus multiproc support
     if not os.environ.get("PROMETHEUS_MULTIPROC_DIR"):
@@ -67,12 +113,13 @@ def execute_from_command_line(argv: list[str]) -> None:
             "checktaskprocessorthreadhealth": healthcheck.main,
         }[subcommand]
     except (IndexError, KeyError):
-        django_execute_from_command_line(argv)
+        logger.info("Invoking Django")
     else:
-        subcommand_main(
+        return subcommand_main(
             argv[2:],
             prog=f"{os.path.basename(argv[0])} {subcommand}",
         )
+    django_execute_from_command_line(argv)
 
 
 def main(argv: list[str] = sys.argv) -> None:

flagsmith_common-3.6.0/src/common/core/otel.py

@@ -0,0 +1,204 @@
+import contextlib
+import json
+from collections.abc import Generator
+from datetime import datetime, timezone
+from importlib.metadata import version
+from typing import cast
+
+import inflection
+import structlog
+from opentelemetry import baggage, trace
+from opentelemetry import context as otel_context
+from opentelemetry._logs import SeverityNumber
+from opentelemetry.baggage.propagation import W3CBaggagePropagator
+from opentelemetry.exporter.otlp.proto.http._log_exporter import (
+    OTLPLogExporter,
+)
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
+    OTLPSpanExporter,
+)
+from opentelemetry.instrumentation.django import DjangoInstrumentor
+from opentelemetry.instrumentation.psycopg2 import Psycopg2Instrumentor
+from opentelemetry.instrumentation.redis import RedisInstrumentor
+from opentelemetry.propagate import set_global_textmap
+from opentelemetry.propagators.composite import CompositePropagator
+from opentelemetry.propagators.textmap import TextMapPropagator
+from opentelemetry.sdk._logs import LoggerProvider
+from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.trace.propagation.tracecontext import (
+    TraceContextTextMapPropagator,
+)
+from opentelemetry.util.types import AnyValue, Attributes
+from structlog.typing import EventDict, Processor
+
+_SEVERITY_MAP: dict[str, SeverityNumber] = {
+    "debug": SeverityNumber.DEBUG,
+    "info": SeverityNumber.INFO,
+    "warning": SeverityNumber.WARN,
+    "error": SeverityNumber.ERROR,
+    "critical": SeverityNumber.FATAL,
+}
+
+_RESERVED_KEYS = frozenset(
+    [
+        "event",
+        "level",
+        "timestamp",
+        "logger",
+        "trace_id",
+        "span_id",
+    ]
+)
+
+
+def add_otel_trace_context(
+    logger: structlog.types.WrappedLogger,
+    method_name: str,
+    event_dict: EventDict,
+) -> EventDict:
+    """Add ``trace_id`` and ``span_id`` from the active OTel span to the event dict."""
+    span = trace.get_current_span()
+    ctx = span.get_span_context()
+    if ctx and ctx.is_valid:
+        event_dict["trace_id"] = f"{ctx.trace_id:032x}"
+        event_dict["span_id"] = f"{ctx.span_id:016x}"
+    return event_dict
+
+
+def make_structlog_otel_processor(logger_provider: LoggerProvider) -> Processor:
+    """Create a structlog processor that emits log records to OpenTelemetry.
+
+    Sits in the processor chain *before* the final renderer so that
+    only structlog-originated logs reach OTel.  Passes the event_dict
+    through unchanged so downstream processors (console/JSON renderers)
+    still work normally.
+
+    Pass the returned processor to :func:`~common.core.logging.setup_logging`
+    via ``otel_processor``.
+    """
+    otel_logger = logger_provider.get_logger(__name__, version("flagsmith-common"))
+
+    def processor(
+        logger: structlog.types.WrappedLogger,
+        method_name: str,
+        event_dict: EventDict,
+    ) -> EventDict:
+        attributes = map_event_dict_to_otel_attributes(event_dict)
+
+        # Copy W3C baggage entries into log attributes so downstream
+        # exporters can access them.
+        ctx = otel_context.get_current()
+        for key, value in baggage.get_all(ctx).items():
+            attributes[key] = str(value)
+
+        body = event_dict.get("event", "")
+        logger_name = event_dict.get("logger")
+        event_name = inflection.underscore(body) if body else "unknown"
+        if logger_name:
+            event_name = f"{logger_name}.{event_name}"
+
+        # Some observability platforms don't surface OTel's EventName.
+        # Keep a custom attribute for better visibility.
+        attributes["flagsmith.event"] = event_name
+
+        log_level = event_dict.get("level", method_name)
+
+        otel_logger.emit(
+            timestamp=int(datetime.now(timezone.utc).timestamp() * 1e9),
+            context=otel_context.get_current(),
+            severity_text=log_level,
+            severity_number=_SEVERITY_MAP.get(log_level, SeverityNumber.TRACE),
+            body=body,
+            event_name=event_name,
+            attributes=attributes,
+        )
+
+        # Also attach as a span event if there's an active span.
+        span = trace.get_current_span()
+        if span.is_recording():
+            # AnyValue is a superset of AttributeValue at runtime;
+            # the cast keeps mypy happy.
+            span.add_event(event_name, attributes=cast(Attributes, attributes))
+
+        return event_dict
+
+    return processor
+
+
+def map_event_dict_to_otel_attributes(event_dict: EventDict) -> dict[str, AnyValue]:
+    return {
+        k.replace("__", "."): map_value_to_otel_value(v)
+        for k, v in event_dict.items()
+        if k not in _RESERVED_KEYS
+    }
+
+
+def map_value_to_otel_value(value: object) -> str | int | float | bool:
+    """Coerce a value to an OTel-attribute-compatible type."""
+    if isinstance(value, (bool, str, int, float)):
+        return value
+    return json.dumps(value, default=str)
+
+
+def build_otel_log_provider(*, endpoint: str, service_name: str) -> LoggerProvider:
+    """Create and configure an OTel LoggerProvider with OTLP/HTTP export."""
+    resource = Resource.create({"service.name": service_name})
+    provider = LoggerProvider(resource=resource)
+    exporter = OTLPLogExporter(endpoint=endpoint)
+    provider.add_log_record_processor(BatchLogRecordProcessor(exporter))
+    return provider
+
+
+def build_tracer_provider(*, endpoint: str, service_name: str) -> TracerProvider:
+    """Create a TracerProvider with OTLP/HTTP export."""
+    resource = Resource.create({"service.name": service_name})
+    tracer_provider = TracerProvider(resource=resource)
+    span_exporter = OTLPSpanExporter(endpoint=endpoint)
+    tracer_provider.add_span_processor(BatchSpanProcessor(span_exporter))
+    return tracer_provider
+
+
+@contextlib.contextmanager
+def setup_tracing(
+    tracer_provider: TracerProvider,
+    excluded_urls: str | None = None,
+) -> Generator[None, None, None]:
+    """Set up and tear down OTel distributed tracing with Django instrumentation.
+
+    Sets the global TracerProvider, configures W3C trace context +
+    baggage propagation, and instruments Django so that every request
+    creates a span with the incoming trace context.
+
+    On exit, uninstruments Django and shuts down the tracer provider.
+
+    Must be called *before* Django's WSGI app is created.
+
+    Args:
+        tracer_provider: The TracerProvider to use.
+        excluded_urls: Comma-separated URL paths to exclude from tracing
+            (e.g. ``"health/liveness,health/readiness"``). If not provided,
+            falls back to the ``OTEL_PYTHON_DJANGO_EXCLUDED_URLS`` env var.
+    """
+    trace.set_tracer_provider(tracer_provider)
+
+    propagator: TextMapPropagator = CompositePropagator(
+        [
+            TraceContextTextMapPropagator(),
+            W3CBaggagePropagator(),
+        ]
+    )
+    set_global_textmap(propagator)
+
+    DjangoInstrumentor().instrument(excluded_urls=excluded_urls)
+    Psycopg2Instrumentor().instrument(enable_commenter=True, skip_dep_check=True)
+    RedisInstrumentor().instrument()
+    try:
+        yield
+    finally:
+        RedisInstrumentor().uninstrument()
+        Psycopg2Instrumentor().uninstrument()
+        DjangoInstrumentor().uninstrument()
+        tracer_provider.shutdown()

flagsmith_common-3.6.0/src/common/core/sentry.py

@@ -0,0 +1,22 @@
+import sentry_sdk
+from structlog.typing import EventDict, WrappedLogger
+
+_SKIP_CONTEXT_FIELDS = frozenset({"event", "level", "timestamp", "_record"})
+
+
+def sentry_processor(
+    logger: WrappedLogger,
+    method_name: str,
+    event_dict: EventDict,
+) -> EventDict:
+    """
+    Structlog processor that enriches Sentry with structured context and tags.
+
+    Since structlog routes through stdlib, Sentry's LoggingIntegration
+    automatically captures ERROR+ logs as Sentry events. This processor
+    adds structured context on top of that.
+    """
+    context = {k: v for k, v in event_dict.items() if k not in _SKIP_CONTEXT_FIELDS}
+    sentry_sdk.set_context("structlog", context)
+
+    return event_dict