`@netscript/telemetry`

OpenTelemetry tracing primitives, context propagation, instrumentation registries, and NetScript runtime adapters for jobs, queues, RPC, and SSE. This page is written against the package's public surface reported by deno doc. For the full index of packages and plugins return to the reference overview.

The root entrypoint (@netscript/telemetry) exposes the stable package diagnostic and instrumentation registry contract only. Runtime helpers live on typed sub-path exports so callers import just the layer they need:

@netscript/telemetry/config — telemetry configuration and OTEL env resolution.
@netscript/telemetry/tracer — tracer accessors and span helpers.
@netscript/telemetry/context — W3C trace context propagation.
@netscript/telemetry/attributes — semantic attribute and span-name constants.
@netscript/telemetry/instrumentation — worker/queue/scheduler/SSE instrumentation.
@netscript/telemetry/registry — instrumentation lifecycle registry.
@netscript/telemetry/orpc — oRPC tracing and error-handling plugins.

Root entrypoint

Diagnostics, traced-job helpers, and the instrumentation registry contract.

Functions

Symbol	Signature	Description
`inspectTelemetry`	`function inspectTelemetry(target): InspectionReport`	Inspect a telemetry target and return a JSON-stable diagnostic report.
`initJobTracing`	`function initJobTracing(): Context \| null`	Initialize tracing in a job subprocess, continuing the trace from the worker.
`runTracedJob`	`async function runTracedJob<T>(jobId: string, fn): Promise<T>`	Wrap a job main function with context extraction and span creation.

Classes

Symbol	Signature	Description
`InstrumentationRegistry`	`class InstrumentationRegistry`	Registry for telemetry instrumentation lifecycle hooks (`register`, `resolve`, `list`, `setupAll`, `teardownAll`).
`DuplicateInstrumentationError`	`class DuplicateInstrumentationError extends Error`	Error thrown when an instrumentation registration name is duplicated.

Types

Symbol	Kind	Description
`InspectionReport`	interface	JSON-stable diagnostic report returned by telemetry inspectors.
`InstrumentationContext`	interface	Context supplied to instrumentation lifecycle hooks.
`InstrumentationEntry`	interface	Diagnostic snapshot of a registry entry.
`InstrumentationRegistration`	interface	Instrumentation lifecycle hooks accepted by `InstrumentationRegistry.register`.

Configuration (`@netscript/telemetry/config`)

Symbol	Signature	Description
`getTelemetryConfig`	`function getTelemetryConfig(): TelemetryConfig`	Resolve the telemetry configuration from the environment.
`getConfig`	`function getConfig(): TelemetryConfig`	Get the cached singleton telemetry configuration.
`resetConfig`	`function resetConfig(): void`	Reset the cached singleton configuration.
`describeTelemetryConfig`	`function describeTelemetryConfig(): TelemetryConfigDescription`	Describe the effective configuration for diagnostics.
`isTelemetryEnabled`	`function isTelemetryEnabled(): boolean`	Whether telemetry is enabled in the current environment.
`getServiceName`	`function getServiceName(): string`	Resolve the configured OTEL service name.
`getOtlpEndpoint`	`function getOtlpEndpoint(): string \| undefined`	Resolve the OTLP exporter endpoint, if set.
`getOtelEnvVars`	`function getOtelEnvVars(): Record<string, string>`	Collect the resolved OTEL environment variables.
`OTEL_ENV_VARS`	`const OTEL_ENV_VARS`	Map of the supported OTEL environment variable names.
`TelemetryConfig`	interface	Resolved telemetry configuration shape.
`TelemetryConfigDescription`	interface	Human-readable configuration description.

Tracer (`@netscript/telemetry/tracer`)

Symbol	Signature	Description
`getTracer`	`function getTracer(name: string, version: string): Tracer`	Get a named tracer at a version.
`getQueueTracer`	`function getQueueTracer(): Tracer`	Tracer for queue operations.
`getWorkerTracer`	`function getWorkerTracer(): Tracer`	Tracer for worker operations.
`getSchedulerTracer`	`function getSchedulerTracer(): Tracer`	Tracer for scheduler operations.
`getJobTracer`	`function getJobTracer(): Tracer`	Tracer for job operations.
`getSagaTracer`	`function getSagaTracer(): Tracer`	Tracer for saga operations.
`getSSETracer`	`function getSSETracer(): Tracer`	Tracer for SSE operations.
`getKVTracer`	`function getKVTracer(): Tracer`	Tracer for KV operations.
`createSpan`	`function createSpan(tracer, name, options): Span`	Create a span on the given tracer.
`withSpan`	`async function withSpan<T>(tracer, name, fn, options): Promise<T>`	Run an async function inside a span.
`withSpanSync`	`function withSpanSync<T>(tracer, name, fn, options): T`	Run a sync function inside a span.
`getActiveSpan`	`function getActiveSpan(): Span \| undefined`	Get the currently active span.
`getActiveContext`	`function getActiveContext(): Context`	Get the currently active context.
`addSpanEvent`	`function addSpanEvent(span, name, attributes?): void`	Add an event to a span.
`setSpanAttributes`	`function setSpanAttributes(span, attributes): void`	Set attributes on a span.
`setSpanError`	`function setSpanError(span, message, error?): void`	Mark a span as errored.
`setSpanOk`	`function setSpanOk(span): void`	Mark a span status as OK.
`isTracingEnabled`	`function isTracingEnabled(): boolean`	Whether tracing is currently enabled.
`TracerNames`	`const TracerNames`	Canonical tracer names: QUEUE, WORKER, SCHEDULER, JOB, SAGA, SSE, KV, DEFAULT.
`SpanKind`	`const SpanKind` / `type SpanKind`	Span kind enum: INTERNAL, SERVER, CLIENT, PRODUCER, CONSUMER.
`SpanStatusCode`	`const SpanStatusCode` / `type SpanStatusCode`	Span status code enum: UNSET, OK, ERROR.
`Context`, `Span`, `Tracer`, `CreateSpanOptions`, `Link`, `Attributes`	type aliases / interfaces	Core OpenTelemetry-compatible span and context types.

Context (`@netscript/telemetry/context`)

W3C trace-context propagation across job subprocesses and message headers.

Symbol	Signature	Description
`withContext`	`function withContext<T>(ctx, fn): T`	Run a sync function with the given context active.
`withContextAsync`	`async function withContextAsync<T>(ctx, fn): Promise<T>`	Run an async function with the given context active.
`contextWithSpan`	`function contextWithSpan(span, parentContext?): Context`	Build a context carrying the given span.
`getSpanFromContext`	`function getSpanFromContext(ctx): Span \| undefined`	Extract the span from a context.
`getTraceId`	`function getTraceId(ctx?): string \| undefined`	Get the trace id from a context.
`getSpanId`	`function getSpanId(ctx?): string \| undefined`	Get the span id from a context.
`hasActiveSpan`	`function hasActiveSpan(ctx?): boolean`	Whether a context carries an active span.
`injectContext`	`function injectContext(headers, ctx?): PropagationHeaders`	Inject context into propagation headers.
`extractContext`	`function extractContext(headers): Context`	Extract a context from propagation headers.
`createMessageHeaders`	`function createMessageHeaders(additionalHeaders): PropagationHeaders`	Build message headers with trace context.
`formatTraceparent`	`function formatTraceparent(spanContext): string`	Format a `traceparent` header value.
`parseTraceparent`	`function parseTraceparent(traceparent): ParsedTraceparent \| null`	Parse a `traceparent` header value.
`resolveParentContextFromHeaders`	`function resolveParentContextFromHeaders(headers?): Context`	Resolve a parent context from headers.
`resolveTraceContext`	`function resolveTraceContext(ctx?): SerializedTraceContext \| null`	Serialize the active trace context.
`resolveTraceContextFromSpan`	`function resolveTraceContextFromSpan(span): SerializedTraceContext`	Serialize trace context from a span.
`extractFromTraceContext`	`function extractFromTraceContext(traceContext): Context`	Rehydrate a context from a serialized payload.
`createJobTraceEnv`	`function createJobTraceEnv(ctx?): JobTraceEnv`	Build job subprocess env carrying trace context.
`extractJobTraceContext`	`function extractJobTraceContext(): Context \| null`	Extract trace context from the job subprocess env.
`JobTraceEnv`, `ParsedTraceparent`, `SerializedTraceContext`	interfaces	Context-propagation payload shapes.

Attributes (`@netscript/telemetry/attributes`)

Semantic attribute keys, span-name constants, and attribute builders. The TC-1..TC-14 checklist is published in convention.md.

Symbol	Signature	Description
`spanName`	`function spanName(base: string, suffix?: string): string`	Compose a namespaced span name.
`createJobAttributes`	`function createJobAttributes(job): Record<string, AttributeValue>`	Build job span attributes with beta.5 deprecated aliases.
`createMessagingAttributes`	`function createMessagingAttributes(options): Record<string, AttributeValue>`	Build messaging span attributes.
`createSagaAttributes`	`function createSagaAttributes(saga): Record<string, AttributeValue>`	Build saga span attributes with beta.5 deprecated aliases.
`createExecutionAttributes`	`function createExecutionAttributes(execution): Record<string, AttributeValue>`	Build execution lifecycle span attributes.
`createGenAiAttributes`	`function createGenAiAttributes(genai): Record<string, AttributeValue>`	Build GenAI semantic-convention attributes.
`createTriggerAttributes`	`function createTriggerAttributes(trigger): Record<string, string>`	Build trigger span attributes.
`createTriggerFileAttributes`	`function createTriggerFileAttributes(payload): Record<string, string \| number>`	Build file-trigger span attributes.
`CacheAttributes`	`const CacheAttributes`	Cache-topology attribute-name constants for the published `netscript.cache.*` compatibility surface; the operation key is the shared `netscript.operation`.
`CacheOperations`	`const CacheOperations`	Logical span-name verbs: `cache.read`, `cache.write`, and `cache.invalidate`; promotion is a `cache.promote` event, not a fourth operation verb.
`CacheOperation`	`type CacheOperation`	Union of the logical cache-operation verbs in `CacheOperations`.
`CacheTiers`	`const CacheTiers`	Runtime-validated cache tiers: `l1`, `l2`, and `durable`.
`CacheTier`	`type CacheTier = 'l1' \| 'l2' \| 'durable'`	Bounded cache-tier identifier accepted by cache-topology attributes.
`CacheOutcomes`	`const CacheOutcomes`	Bounded results: `hit`, `miss`, `stale`, and `error`. An unknowable successful provider chain sets `topology_complete=false` and omits `outcome`; `error` is emitted only when the operation throws.
`CacheOutcome`	`type CacheOutcome = 'hit' \| 'miss' \| 'stale' \| 'error'`	Union of the bounded lookup and mutation outcomes in `CacheOutcomes`.
`CacheAttributeOptions`	`type CacheAttributeOptions`	Bounded operation, provider, namespace, tier, outcome, timing, loader, and topology facts accepted by the cache attribute builder; it has no cache-key field.
`createCacheAttributes`	`function createCacheAttributes(options: CacheAttributeOptions): TelemetryAttributeBuilderMap`	Build bounded cache-topology attributes. The API accepts no cache key, making raw-key leakage structurally impossible.
`TelemetryConventionChecklist`	`const TelemetryConventionChecklist`	TC-1..TC-14 conformance checklist.
`SpanNames`	`const SpanNames`	Canonical span-name constants for scheduler, queue, worker, job, saga, execution, RPC, GenAI, SSE, KV, and trigger spans.
`NetScriptAttributeDomains`	`const NetScriptAttributeDomains`	Single-root `netscript.*` proprietary attribute domains.
`NetScriptCorrelationAttributes`	`const NetScriptCorrelationAttributes`	Shared `netscript.correlation.id` attribute floor.
`ExecutionAttributes` / `NetScriptExecutionAttributes`	`const`	Deprecated execution aliases and canonical execution lifecycle attribute keys.
`JobAttributes` / `NetScriptJobAttributes` / `JobStatuses` / `JobTriggers`	const	Deprecated job aliases, canonical job keys, and enumerated status/trigger values.
`WorkerAttributes`	`const WorkerAttributes`	Worker attribute keys.
`SchedulerAttributes`	`const SchedulerAttributes`	Scheduler attribute keys.
`MessagingAttributes` / `MessagingOperations` / `MessagingSystems`	const	Messaging attribute keys and enumerated operations/systems.
`SagaAttributes`	`const SagaAttributes`	Saga attribute keys.
`GenAiAttributes`	`const GenAiAttributes`	GenAI semantic-convention attribute keys.
`KVAttributes` / `KVOperations`	const	KV attribute keys and operation values.
`SSEAttributes`	`const SSEAttributes`	SSE attribute keys.
`TriggerAttributes`	`const TriggerAttributes`	Trigger attribute keys.

Instrumentation (`@netscript/telemetry/instrumentation`)

Span builders and recorders for workers, queues, schedulers, SSE, and job dispatch.

Symbol	Signature	Description
`startWorkerSpan`	`function startWorkerSpan(config): Span`	Start a worker span.
`createWorkerStopSpan`	`function createWorkerStopSpan(workerId, activeJobs): Span`	Span for worker shutdown.
`recordWorkerMetrics`	`function recordWorkerMetrics(span, metrics): void`	Record worker metrics on a span.
`traceJobExecution`	`async function traceJobExecution<T>(options, fn): Promise<T>`	Trace a job execution.
`createJobSpawnSpan`	`function createJobSpawnSpan(job, executionId): Span`	Span for spawning a job subprocess.
`createJobSubprocessEnv`	`function createJobSubprocessEnv(additionalEnv): Record<string, string>`	Build the traced subprocess env.
`getJobTraceContext`	`function getJobTraceContext(): SerializedTraceContext \| null`	Read serialized trace context in a job.
`initJobTracing`	`function initJobTracing(): Context \| null`	Initialize tracing in a job subprocess.
`runTracedJob`	`async function runTracedJob<T>(jobId, fn): Promise<T>`	Wrap a job main with tracing.
`addJobStepEvent`	`function addJobStepEvent(stepName, attributes?): void`	Add a step event to the active job span.
`recordJobProgress`	`function recordJobProgress(current, total, unit): void`	Record job progress on the active span.
`startJobDispatchSpan`	`function startJobDispatchSpan(context, options)`	Start a job-dispatch span and propagation headers.
`traceJobDispatch`	`async function traceJobDispatch(context, fn, options): Promise<void>`	Trace a job dispatch.
`isTracedQueue`	`function isTracedQueue<T>(queue): queue is TracedQueue<T>`	Type guard for a traced queue.
`startSchedulerTickSpan`	`function startSchedulerTickSpan(context): Span`	Span for a scheduler tick.
`createSchedulerStartSpan`, `createSchedulerStopSpan`	functions returning `Span`	Spans for scheduler start/stop.
`createScheduleJobSpan`, `createUnscheduleJobSpan`	functions returning `Span`	Root spans for scheduling/unscheduling a job.
`recordCronJobRun`, `recordSchedulerReload`	functions returning `void`	Record scheduler run/reload outcomes.

Registry (`@netscript/telemetry/registry`)

Instrumentation lifecycle registry (also re-exported from the root entrypoint).

Symbol	Kind	Description
`InstrumentationRegistry`	class	Registry for instrumentation lifecycle hooks.
`DuplicateInstrumentationError`	class	Duplicate registration name error.
`InstrumentationContext`	interface	Lifecycle hook context.
`InstrumentationEntry`	interface	Diagnostic registry snapshot.
`InstrumentationRegistration`	interface	Registered lifecycle hooks.

oRPC (`@netscript/telemetry/orpc`)

Tracing and error-handling plugins for the NetScript oRPC handler.

Symbol	Signature	Description
`createTracingPlugin`	`function createTracingPlugin(options?): TracingPlugin`	Create the oRPC tracing plugin.
`TracingPlugin`	`class TracingPlugin`	oRPC tracing plugin.
`createErrorHandlingPlugin`	`function createErrorHandlingPlugin(options?): ErrorHandlingPlugin`	Create the oRPC error-handling plugin.
`ErrorHandlingPlugin`	`class ErrorHandlingPlugin`	oRPC error-handling plugin.
`createTraceContext`	`function createTraceContext(): TraceContext`	Create a handler-scoped trace context.
`addEvent`	`function addEvent(name, attributes?): void`	Add an event to the active handler span.
`setAttributes`	`function setAttributes(attributes): void`	Set attributes on the active handler span.
`getTraceId`, `getSpanId`	functions returning `string \| undefined`	Read the active handler trace/span id.
`TraceContext`	interface	Handler-scoped trace context contract.
`TracingPluginOptions`, `ErrorHandlingPluginOptions`	interfaces	Plugin options.
`ErrorContext`, `ErrorLogger`	interfaces	Error plugin payload and logger contracts.

Sub-path exports

The following entrypoints are published alongside the root export. Each is documented against its own deno doc surface.

Export	Entrypoint	Purpose
`@netscript/telemetry`	`./mod.ts`	Diagnostics + instrumentation registry contract (documented above).
`@netscript/telemetry/config`	`./config.ts`	Telemetry configuration and OTEL env resolution.
`@netscript/telemetry/tracer`	`./tracer.ts`	Tracer accessors and span helpers.
`@netscript/telemetry/context`	`./context.ts`	W3C trace-context propagation.
`@netscript/telemetry/attributes`	`./attributes.ts`	Semantic attribute and span-name constants.
`@netscript/telemetry/instrumentation`	`./instrumentation.ts`	Worker/queue/scheduler/SSE instrumentation.
`@netscript/telemetry/registry`	`./registry.ts`	Instrumentation lifecycle registry.
`@netscript/telemetry/orpc`	`./orpc.ts`	oRPC tracing and error-handling plugins.
`@netscript/telemetry/hono`	`./hono.ts`	Hono request and response tracing middleware.
`@netscript/telemetry/ai`	`./ai.ts`	GenAI request, token, and chat-client metrics and tracing.
`@netscript/telemetry/otel`	`./src/adapters/otel/mod.ts`	OpenTelemetry Deno provider adapters.
`@netscript/telemetry/query`	`./query.ts`	Telemetry query capabilities and filters.
`@netscript/telemetry/testing`	`./src/testing/mod.ts`	In-memory span recorder for test verification.

Back to the reference overview.

@netscript/telemetry

Root entrypoint

Functions

Classes

Types

Configuration (@netscript/telemetry/config)

Tracer (@netscript/telemetry/tracer)

Context (@netscript/telemetry/context)

Attributes (@netscript/telemetry/attributes)

Instrumentation (@netscript/telemetry/instrumentation)

Registry (@netscript/telemetry/registry)

oRPC (@netscript/telemetry/orpc)