Safe Haskell	None
Language	GHC2021

Ecluse.Core.Telemetry.Span

Contents

The serve-path tracing port
The worker tracing port
The advisory sync tracing port
Bracketing a span against an optional tracer

Description

The domain-span tracing ports, and the bracket Pilot opens its own spans through.

The serve path, the mirror worker, and the advisory sync task reach their hand-added spans through a port: bracket operations as a record, parametric in the bracketed action's result and naming no OpenTelemetry tracer, so the application supplies the OTel-backed implementations and a test a pass-through double. Pilot's passes run outside a request and hold the TracerProvider themselves, so they bracket through withOptionalSpan instead. Both consumers create their tracer under ecluseScope.

Synopsis

data TracingPort = TracingPort {
- spanRuleEval :: forall a. PackageName -> Version -> IO (a, ServeDecision) -> IO a
- spanMirrorEnqueue :: forall a. PackageName -> Version -> Text -> (a -> Maybe Text) -> (Maybe RemoteSpanContext -> IO a) -> IO a
- spanPackumentGate :: forall a. PackageName -> IO a -> IO a
- spanMetadataFetch :: forall a. PackageName -> IO a -> IO a
- spanMetadataDecode :: forall a. PackageName -> IO a -> IO a
}
newtype WorkerTracingPort = WorkerTracingPort {
- wtpMirrorJobSpan :: forall a. PackageName -> Version -> Maybe RemoteSpanContext -> (a -> JobSpanOutcome) -> IO a -> IO a
}
data JobSpanOutcome = JobSpanOutcome {
- jobSpanLabel :: Text
- jobSpanError :: Maybe Text
}
newtype AdvisorySyncTracingPort = AdvisorySyncTracingPort {
- astpSyncAttemptSpan :: forall a. Ecosystem -> (a -> AdvisorySyncResult) -> IO a -> IO a
}
ecluseScope :: IsString s => s
withOptionalSpan :: MonadUnliftIO m => Maybe TracerProvider -> SpanKind -> Text -> (Maybe Span -> m a) -> m a
openOptionalSpan :: MonadIO m => Maybe TracerProvider -> SpanKind -> Text -> m (Maybe Span)
closeOptionalSpan :: MonadIO m => Maybe Span -> m ()

The serve-path tracing port

data TracingPort Source #

The domain-span tracing port: bracket operations over a backend whose closure captures its tracer. The implementation is inert when tracing is off, so a call site brackets unconditionally.

Constructors

TracingPort

Fields

spanRuleEval :: forall a. PackageName -> Version -> IO (a, ServeDecision) -> IO a
Bracket the per-version rule evaluation. The ServeDecision the body yields goes on the span, so a refusal is explainable from the trace alone.
spanMirrorEnqueue :: forall a. PackageName -> Version -> Text -> (a -> Maybe Text) -> (Maybe RemoteSpanContext -> IO a) -> IO a
Bracket the serve-time hand-off to the asynchronous mirror. The body stamps the supplied span context onto the job, linking the worker's span across the async hop.
spanPackumentGate :: forall a. PackageName -> IO a -> IO a
Bracket the gating phase of a packument request, which runs the rules and filter on the public upstream document.
spanMetadataFetch :: forall a. PackageName -> IO a -> IO a
Bracket one upstream metadata fetch, refusals included.
spanMetadataDecode :: forall a. PackageName -> IO a -> IO a
Bracket extraction after a successful metadata response. Streaming body reads can occur inside.

The worker tracing port

newtype WorkerTracingPort Source #

The mirror worker's domain-span tracing port: the worker analogue of TracingPort. The implementation is inert when tracing is off, so the worker brackets unconditionally.

Constructors

WorkerTracingPort
Fields wtpMirrorJobSpan :: forall a. PackageName -> Version -> Maybe RemoteSpanContext -> (a -> JobSpanOutcome) -> IO a -> IO a Bracket the worker's per-job fetch, verify, and publish. The supplied context links the span back to the enqueueing request, and is `Nothing` when the job carried none.

data JobSpanOutcome Source #

The outcome projection a caller supplies for the mirror-job span. It is its own record so the tracing port does not depend on the worker loop.

Constructors

JobSpanOutcome
Fields jobSpanLabel :: Text The bounded outcome label (e.g. `succeeded` / `dropped` / `retried`). jobSpanError :: Maybe Text The failure detail when the job did not publish. `Nothing` on success.

Instances

Instances details

Show JobSpanOutcome Source #
Instance details Defined in Ecluse.Core.Telemetry.Span Methods showsPrec :: Int -> JobSpanOutcome -> ShowS # show :: JobSpanOutcome -> String # showList :: [JobSpanOutcome] -> ShowS #
Eq JobSpanOutcome Source #
Instance details Defined in Ecluse.Core.Telemetry.Span Methods (==) :: JobSpanOutcome -> JobSpanOutcome -> Bool # (/=) :: JobSpanOutcome -> JobSpanOutcome -> Bool #

The advisory sync tracing port

newtype AdvisorySyncTracingPort Source #

One span per advisory sync attempt. It carries the same AdvisorySyncResult that labels the attempt metrics, so a trace and a series join on one vocabulary.

Constructors

AdvisorySyncTracingPort
Fields astpSyncAttemptSpan :: forall a. Ecosystem -> (a -> AdvisorySyncResult) -> IO a -> IO a Bracket one advisory sync attempt for an ecosystem, recording the projected result.

Bracketing a span against an optional tracer

ecluseScope :: IsString s => s Source #

The instrumentation scope the hand-added spans and the WAI meter are created under, so the signals are attributed to Écluse rather than to a third-party instrumentation library.

withOptionalSpan :: MonadUnliftIO m => Maybe TracerProvider -> SpanKind -> Text -> (Maybe Span -> m a) -> m a Source #

Run body against a span opened on mTracerProvider, or against Nothing when there is none, which opens no span. The span roots its own trace: no ambient context is consulted.

openOptionalSpan :: MonadIO m => Maybe TracerProvider -> SpanKind -> Text -> m (Maybe Span) Source #

The acquire half of withOptionalSpan, for a conduit pass that brackets through bracketP rather than bracket.

closeOptionalSpan :: MonadIO m => Maybe Span -> m () Source #

The release half of withOptionalSpan. Ending at the current instant, as Nothing asks.