flightdeck-sensor 0.3.0

In-process agent observability sensor for Flightdeck

flightdeck-sensor

In-process agent observability sensor for Flightdeck.

Optional session_id hint (D094)

By default init() auto-generates a fresh UUID every time the process starts. Orchestrators that re-run the same logical workflow (Temporal, Airflow, cron) can instead pass a stable identifier; if the backend already has a row for that session, the new execution is attached to it and appears as a continuation of the prior run in the fleet view.

Supply the hint via either the session_id= kwarg or the FLIGHTDECK_SESSION_ID environment variable. The env var takes precedence.

The value MUST parse as a canonical UUID (any version) -- the sessions table column is UUID-typed. If you pass a non-UUID the sensor logs a warning and falls back to auto-generating one. Orchestrators that use string identifiers (Temporal workflow_id, Airflow dag_run_id) should hash the identifier into a deterministic UUID with uuid.uuid5.

Temporal workflow example

import uuid
import flightdeck_sensor as fd
from temporalio import workflow

# Pick any fixed namespace UUID for your deployment. The same
# workflow_id + namespace always produces the same session UUID,
# so re-runs of the same workflow all map to the same sessions row.
FLIGHTDECK_NS = uuid.UUID("00000000-0000-0000-0000-000000000001")

@workflow.defn
class MyWorkflow:
    @workflow.run
    async def run(self, input):
        ctx = workflow.info()
        fd.init(
            server="http://flightdeck.internal/ingest",
            token="ftd_...",
            session_id=str(uuid.uuid5(FLIGHTDECK_NS, ctx.workflow_id)),
        )
        # If this workflow_id has run before, the backend attaches
        # this execution to the existing session automatically; the
        # sensor logs INFO on the first response that confirms it.
        ...

The sensor logs a single WARNING at init() time whenever a custom session_id is in play so the behaviour is visible in operational logs, and an INFO line on the first response where the backend confirms attachment. See DECISIONS.md D094 and ARCHITECTURE.md ("Session attachment flow") for the full protocol.