@fedify/fedify/dist/otel/mod.d.ts

An ActivityPub server framework

/// <reference lib="esnext.temporal" />
import { n as KvStore, t as KvKey } from "../kv-D6hNiMTK.js";
import { ExportResultCode } from "@opentelemetry/core";
import { ReadableSpan, SpanExporter } from "@opentelemetry/sdk-trace-base";

//#region src/otel/exporter.d.ts
/**
* The direction of an activity in the trace.
*
* @since 1.10.0
*/
type ActivityDirection = "inbound" | "outbound";
/**
* Signature verification details for an inbound activity.
*
* @since 1.10.0
*/
interface SignatureVerificationDetails {
  /**
  * Whether HTTP Signatures were verified.
  */
  readonly httpSignaturesVerified: boolean;
  /**
  * The key ID used for HTTP signature verification, if available.
  */
  readonly httpSignaturesKeyId?: string;
  /**
  * The reason why HTTP signature verification failed, if available.
  */
  readonly httpSignaturesFailureReason?: string;
  /**
  * The HTTP status code from a failed key fetch, if available.
  */
  readonly httpSignaturesKeyFetchStatus?: number;
  /**
  * The error type from a non-HTTP key fetch failure, if available.
  */
  readonly httpSignaturesKeyFetchError?: string;
  /**
  * Whether Linked Data Signatures were verified.
  */
  readonly ldSignaturesVerified: boolean;
}
/**
* A record of an activity captured from a trace span.
* This interface stores the activity data along with trace context
* for distributed tracing support.
*
* @since 1.10.0
*/
interface TraceActivityRecord {
  /**
  * The trace ID from OpenTelemetry.
  */
  readonly traceId: string;
  /**
  * The span ID from OpenTelemetry.
  */
  readonly spanId: string;
  /**
  * The parent span ID, if any.
  */
  readonly parentSpanId?: string;
  /**
  * Whether this is an inbound or outbound activity.
  */
  readonly direction: ActivityDirection;
  /**
  * The ActivityPub activity type (e.g., "Create", "Follow", "Like").
  */
  readonly activityType: string;
  /**
  * The activity's ID URL, if present.
  */
  readonly activityId?: string;
  /**
  * The actor ID URL (sender of the activity).
  */
  readonly actorId?: string;
  /**
  * The full JSON representation of the activity.
  */
  readonly activityJson: string;
  /**
  * Whether the activity was verified (for inbound activities).
  */
  readonly verified?: boolean;
  /**
  * Detailed signature verification information (for inbound activities).
  */
  readonly signatureDetails?: SignatureVerificationDetails;
  /**
  * The timestamp when this record was created (ISO 8601 format).
  */
  readonly timestamp: string;
  /**
  * The target inbox URL (for outbound activities).
  */
  readonly inboxUrl?: string;
}
/**
* Summary information about a trace.
*
* @since 1.10.0
*/
interface TraceSummary {
  /**
  * The trace ID.
  */
  readonly traceId: string;
  /**
  * The timestamp of the first activity in the trace.
  */
  readonly timestamp: string;
  /**
  * The number of activities in the trace.
  */
  readonly activityCount: number;
  /**
  * Activity types present in this trace.
  */
  readonly activityTypes: readonly string[];
}
/**
* Options for configuring the {@link FedifySpanExporter}.
*
* @since 1.10.0
*/
interface FedifySpanExporterOptions {
  /**
  * The time-to-live for stored trace data.
  * If not specified, data will be stored indefinitely
  * (or until manually deleted).
  */
  readonly ttl?: Temporal.Duration;
  /**
  * The key prefix for storing trace data in the KvStore.
  * Defaults to `["fedify", "traces"]`.
  */
  readonly keyPrefix?: KvKey;
}
/**
* Options for the {@link FedifySpanExporter.getRecentTraces} method.
*
* @since 1.10.0
*/
interface GetRecentTracesOptions {
  /**
  * Maximum number of traces to return.
  * If not specified, returns all available traces.
  */
  limit?: number;
}
/**
* A SpanExporter that persists ActivityPub activity traces to a
* {@link KvStore}.  This enables distributed tracing across multiple
* nodes in a Fedify deployment.
*
* The exporter captures activity data from OpenTelemetry span events
* (`activitypub.activity.received` and `activitypub.activity.sent`)
* and stores them in the KvStore with trace context preserved.
*
* @example Basic usage with MemoryKvStore
* ```typescript ignore
* import { MemoryKvStore } from "@fedify/fedify";
* import { FedifySpanExporter } from "@fedify/fedify/otel";
* import {
*   BasicTracerProvider,
*   SimpleSpanProcessor,
* } from "@opentelemetry/sdk-trace-base";
*
* const kv = new MemoryKvStore();
* const exporter = new FedifySpanExporter(kv, {
*   ttl: Temporal.Duration.from({ hours: 1 }),
* });
*
* const provider = new BasicTracerProvider({
*   spanProcessors: [new SimpleSpanProcessor(exporter)],
* });
* ```
*
* @example Querying stored traces
* ```typescript ignore
* import { MemoryKvStore } from "@fedify/fedify";
* import { FedifySpanExporter } from "@fedify/fedify/otel";
*
* const kv = new MemoryKvStore();
* const exporter = new FedifySpanExporter(kv);
* const traceId = "abc123";
*
* // Get all activities for a specific trace
* const activities = await exporter.getActivitiesByTraceId(traceId);
*
* // Get recent traces
* const recentTraces = await exporter.getRecentTraces({ limit: 100 });
* ```
*
* @since 1.10.0
*/
declare class FedifySpanExporter implements SpanExporter {
  #private;
  /**
  * Creates a new FedifySpanExporter.
  *
  * @param kv The KvStore to persist trace data to.
  * @param options Configuration options.
  */
  constructor(kv: KvStore, options?: FedifySpanExporterOptions);
  /**
  * Exports spans to the KvStore.
  *
  * @param spans The spans to export.
  * @param resultCallback Callback to invoke with the export result.
  */
  export(spans: ReadableSpan[], resultCallback: (result: {
    code: ExportResultCode;
  }) => void): void;
  /**
  * Gets all activity records for a specific trace ID.
  *
  * @param traceId The trace ID to query.
  * @returns An array of activity records belonging to the trace.
  */
  getActivitiesByTraceId(traceId: string): Promise<TraceActivityRecord[]>;
  /**
  * Gets recent traces with summary information.
  *
  * @param options Options for the query.
  * @returns An array of trace summaries.
  */
  getRecentTraces(options?: GetRecentTracesOptions): Promise<TraceSummary[]>;
  /**
  * Forces the exporter to flush any buffered data.
  * This is a no-op because we write directly to the KvStore without buffering.
  */
  forceFlush(): Promise<void>;
  /**
  * Shuts down the exporter.
  */
  shutdown(): Promise<void>;
}
//#endregion
export { type ActivityDirection, FedifySpanExporter, type FedifySpanExporterOptions, type GetRecentTracesOptions, type SignatureVerificationDetails, type TraceActivityRecord, type TraceSummary };