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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flagsmith-common
-Version: 3.6.0
+Version: 3.7.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
@@ -38,6 +38,7 @@ Requires-Dist: flagsmith-flag-engine>6 ; extra == 'flagsmith-schemas'
 Requires-Dist: backoff>=2.2.1,<3.0.0 ; extra == 'task-processor'
 Requires-Dist: django>4,<6 ; extra == 'task-processor'
 Requires-Dist: django-health-check ; extra == 'task-processor'
+Requires-Dist: opentelemetry-api>=1.25,<2 ; extra == 'task-processor'
 Requires-Dist: prometheus-client>=0.0.16 ; extra == 'task-processor'
 Requires-Dist: pyfakefs>=5,<6 ; extra == 'test-tools'
 Requires-Dist: pytest-django>=4,<5 ; extra == 'test-tools'
@@ -164,7 +165,7 @@ 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_SERVICE_NAME`               | The `service.name` resource attribute. Defaults to `flagsmith-task-processor` when running the task processor.         | `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.
@@ -178,6 +179,7 @@ When `OTEL_EXPORTER_OTLP_ENDPOINT` is set, `ensure_cli_env()` sets up:
   - **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).
+- **Task processor trace propagation**: When a task is enqueued via `TaskHandler.delay()`, the current W3C trace context (including baggage) is serialized into the task's `trace_context` field. When the task processor executes the task, the context is extracted and a child span is created, linking the task execution back to the originating request trace. Span attributes (`task_identifier`, `task_type`, `result`) match the Prometheus metric labels for cross-signal correlation.
 
 #### Emitting OTel log events via structlog
 

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

@@ -107,7 +107,7 @@ 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_SERVICE_NAME`               | The `service.name` resource attribute. Defaults to `flagsmith-task-processor` when running the task processor.         | `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.
@@ -121,6 +121,7 @@ When `OTEL_EXPORTER_OTLP_ENDPOINT` is set, `ensure_cli_env()` sets up:
   - **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).
+- **Task processor trace propagation**: When a task is enqueued via `TaskHandler.delay()`, the current W3C trace context (including baggage) is serialized into the task's `trace_context` field. When the task processor executes the task, the context is extracted and a child span is created, linking the task execution back to the originating request trace. Span attributes (`task_identifier`, `task_type`, `result`) match the Prometheus metric labels for cross-signal correlation.
 
 #### Emitting OTel log events via structlog
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "flagsmith-common"
-version = "3.6.0"
+version = "3.7.0"
 description = "Flagsmith's common library"
 requires-python = ">=3.11,<4.0"
 dependencies = []
@@ -35,6 +35,7 @@ optional-dependencies = { test-tools = [
     "backoff (>=2.2.1,<3.0.0)",
     "django (>4,<6)",
     "django-health-check",
+    "opentelemetry-api (>=1.25,<2)",
     "prometheus-client (>=0.0.16)",
 ], flagsmith-schemas = [
     "simplejson",

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

@@ -37,7 +37,24 @@ def ensure_cli_env() -> typing.Generator[None, None, None]:
     """
     ctx = contextlib.ExitStack()
 
+    # Currently we don't install Flagsmith modules as a package, so we need to add
+    # $CWD to the Python path to be able to import them
+    sys.path.append(os.getcwd())
+
+    # TODO @khvn26 We should find a better way to pre-set the Django settings module
+    # without resorting to it being set outside of the application
+    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "settings.dev")
+
+    if "docgen" in sys.argv:
+        os.environ["DOCGEN_MODE"] = "true"
+
+    if "task-processor" in sys.argv:
+        # A hacky way to signal we're not running the API
+        os.environ["RUN_BY_PROCESSOR"] = "true"
+
     # Set up OTel instrumentation (opt-in via OTEL_EXPORTER_OTLP_ENDPOINT).
+    # Must come after sys.path / DJANGO_SETTINGS_MODULE setup because
+    # DjangoInstrumentor accesses settings.MIDDLEWARE.
     otel_processors = None
     otel_endpoint = env.str("OTEL_EXPORTER_OTLP_ENDPOINT", None)
     if otel_endpoint:
@@ -49,7 +66,12 @@ def ensure_cli_env() -> typing.Generator[None, None, None]:
             setup_tracing,
         )
 
-        service_name = env.str("OTEL_SERVICE_NAME", "flagsmith-api")
+        default_service_name = (
+            "flagsmith-task-processor"
+            if "task-processor" in sys.argv
+            else "flagsmith-api"
+        )
+        service_name = env.str("OTEL_SERVICE_NAME", default_service_name)
         log_provider = build_otel_log_provider(
             endpoint=f"{otel_endpoint}/v1/logs",
             service_name=service_name,
@@ -84,21 +106,6 @@ def ensure_cli_env() -> typing.Generator[None, None, None]:
     if not os.environ.get("PROMETHEUS_MULTIPROC_DIR"):
         os.environ["PROMETHEUS_MULTIPROC_DIR"] = mkdtemp(prefix="flagsmith-prometheus-")
 
-    # Currently we don't install Flagsmith modules as a package, so we need to add
-    # $CWD to the Python path to be able to import them
-    sys.path.append(os.getcwd())
-
-    # TODO @khvn26 We should find a better way to pre-set the Django settings module
-    # without resorting to it being set outside of the application
-    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "settings.dev")
-
-    if "docgen" in sys.argv:
-        os.environ["DOCGEN_MODE"] = "true"
-
-    if "task-processor" in sys.argv:
-        # A hacky way to signal we're not running the API
-        os.environ["RUN_BY_PROCESSOR"] = "true"
-
     with ctx:
         yield
 

{flagsmith_common-3.6.0 → flagsmith_common-3.7.0}/src/common/test_tools/types.py

@@ -20,7 +20,7 @@ class AssertMetricFixture(Protocol):
 class RunTasksFixture(Protocol):
     def __call__(
         self,
-        num_tasks: int,
+        num_tasks: int = 1,
     ) -> "list[TaskRun]": ...
 
 

{flagsmith_common-3.6.0 → flagsmith_common-3.7.0}/src/task_processor/decorators.py

@@ -6,12 +6,13 @@ from threading import Thread
 from django.conf import settings
 from django.db.transaction import on_commit
 from django.utils import timezone
+from opentelemetry import propagate
 
 from task_processor import metrics, task_registry
 from task_processor.exceptions import InvalidArgumentsError, TaskQueueFullError
 from task_processor.models import RecurringTask, Task, TaskPriority
 from task_processor.task_run_method import TaskRunMethod
-from task_processor.types import TaskCallable, TaskParameters
+from task_processor.types import TaskCallable, TaskParameters, TraceContext
 from task_processor.utils import get_task_identifier_from_function
 
 logger = logging.getLogger(__name__)
@@ -92,6 +93,8 @@ class TaskHandler(typing.Generic[TaskParameters]):
                 task_identifier=task_identifier
             ).inc()
             try:
+                carrier: TraceContext = {}
+                propagate.inject(carrier)
                 task = Task.create(
                     task_identifier=task_identifier,
                     scheduled_for=delay_until or timezone.now(),
@@ -100,6 +103,7 @@ class TaskHandler(typing.Generic[TaskParameters]):
                     timeout=self.timeout,
                     args=args,
                     kwargs=kwargs,
+                    trace_context=carrier or None,
                 )
             except TaskQueueFullError as e:
                 logger.warning(e)

flagsmith_common-3.7.0/src/task_processor/migrations/0014_add_trace_context.py

@@ -0,0 +1,23 @@
+# Generated by Django 5.2.12 on 2026-04-10 14:29
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("task_processor", "0013_add_last_picked_at"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="recurringtask",
+            name="trace_context",
+            field=models.JSONField(blank=True, null=True),
+        ),
+        migrations.AddField(
+            model_name="task",
+            name="trace_context",
+            field=models.JSONField(blank=True, null=True),
+        ),
+    ]

{flagsmith_common-3.6.0 → flagsmith_common-3.7.0}/src/task_processor/models.py

@@ -10,7 +10,7 @@ from django.utils import timezone
 from task_processor.exceptions import TaskQueueFullError
 from task_processor.managers import RecurringTaskManager, TaskManager
 from task_processor.task_registry import get_task, registered_tasks
-from task_processor.types import TaskCallable
+from task_processor.types import TaskCallable, TraceContext
 
 _django_json_encoder_default = DjangoJSONEncoder().default
 
@@ -31,6 +31,7 @@ class AbstractBaseTask(models.Model):
     serialized_kwargs = models.TextField(blank=True, null=True)
     is_locked = models.BooleanField(default=False)
     timeout = models.DurationField(blank=True, null=True)
+    trace_context = models.JSONField(null=True, blank=True)
 
     class Meta:
         abstract = True
@@ -112,6 +113,7 @@ class Task(AbstractBaseTask):
         args: typing.Tuple[typing.Any, ...] | None = None,
         kwargs: typing.Dict[str, typing.Any] | None = None,
         timeout: timedelta | None = timedelta(seconds=60),
+        trace_context: TraceContext | None = None,
     ) -> "Task":
         if queue_size and cls._is_queue_full(task_identifier, queue_size):
             raise TaskQueueFullError(
@@ -125,6 +127,7 @@ class Task(AbstractBaseTask):
             serialized_args=cls.serialize_data(args or tuple()),
             serialized_kwargs=cls.serialize_data(kwargs or dict()),
             timeout=timeout,
+            trace_context=trace_context,
         )
 
     @classmethod

{flagsmith_common-3.6.0 → flagsmith_common-3.7.0}/src/task_processor/processor.py

@@ -4,9 +4,12 @@ import typing
 from concurrent.futures import ThreadPoolExecutor
 from contextlib import ExitStack
 from datetime import timedelta
+from importlib.metadata import version
 
 from django.conf import settings
 from django.utils import timezone
+from opentelemetry import context as otel_context
+from opentelemetry import propagate, trace
 
 from task_processor import metrics
 from task_processor.exceptions import TaskBackoffError
@@ -130,6 +133,11 @@ def _run_task(
     result: str
     executor = None
 
+    extracted_ctx = propagate.extract(task.trace_context or {})
+    tracer = trace.get_tracer("task_processor", version("flagsmith-common"))
+    span = tracer.start_span(task_identifier, context=extracted_ctx)
+    otel_token = otel_context.attach(trace.set_span_in_context(span, extracted_ctx))
+
     try:
         # Use explicit executor management to avoid blocking on shutdown
         # when tasks timeout but continue running in worker threads.
@@ -151,6 +159,9 @@ def _run_task(
         # fall back to using repr.
         err_msg = str(e) or repr(e)
 
+        span.set_status(trace.StatusCode.ERROR, err_msg)
+        span.record_exception(e)
+
         task.mark_failure()
 
         task_run.result = result = TaskResult.FAILURE.value
@@ -199,4 +210,8 @@ def _run_task(
 
     metrics.flagsmith_task_processor_finished_tasks_total.labels(**labels).inc()
 
+    span.set_attributes(labels)
+    span.end()
+    otel_context.detach(otel_token)
+
     return task, task_run

{flagsmith_common-3.6.0 → flagsmith_common-3.7.0}/src/task_processor/types.py

@@ -5,6 +5,8 @@ TaskParameters = ParamSpec("TaskParameters")
 
 TaskCallable: TypeAlias = Callable[TaskParameters, None]
 
+TraceContext: TypeAlias = dict[str, str]
+
 
 @dataclass
 class TaskProcessorConfig: