@posthog/ai/dist/otel/index.d.ts

PostHog Node.js AI integrations

import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { ReadableSpan, SpanProcessor, Span } from '@opentelemetry/sdk-trace-base';
import { Context } from '@opentelemetry/api';

/**
 * Options for the PostHogTraceExporter. `projectToken` is required; a blank token disables the
 * exporter as a defensive no-op. You can also optionally override the `host` URL. `host` defaults to `https://us.i.posthog.com`.
 *
 * @example
 * ```ts
 * import { PostHogTraceExporter } from '@posthog/ai/otel'
 *
 * new PostHogTraceExporter({ projectToken: 'phc_...' })
 * ```
 *
 * @example
 * ```ts
 * import { PostHogTraceExporter } from '@posthog/ai/otel'
 *
 * new PostHogTraceExporter({ projectToken: 'phc_...', host: 'https://eu.i.posthog.com' })
 * ```
 */
type PostHogTraceExporterOptions = {
    projectToken: string;
    host?: string;
};
/**
 * An OpenTelemetry `TraceExporter` that sends AI traces to PostHog's OTLP
 * ingestion endpoint. PostHog converts `gen_ai.*` spans into
 * `$ai_generation` events server-side.
 *
 * Only AI-related spans (those whose name or attribute keys start with
 * `gen_ai.`, `llm.`, `ai.`, or `traceloop.`) are exported; all other
 * spans are silently dropped.
 *
 * Use this when the API you're integrating with only accepts a
 * `TraceExporter` (e.g. Vercel's `registerOTel`) or when you need to
 * plug PostHog into an existing processor chain. Otherwise prefer
 * {@link PostHogSpanProcessor}, which is self-contained.
 *
 * `projectToken` is required; a blank token disables the exporter as a defensive no-op.
 * You can also optionally override the `host` URL.
 *
 * @example
 * ```ts
 * import { PostHogTraceExporter } from '@posthog/ai/otel'
 * import { registerOTel } from '@vercel/otel'
 *
 * registerOTel({
 *   serviceName: 'my-app',
 *   traceExporter: new PostHogTraceExporter({ projectToken: 'phc_...' }),
 * })
 * ```
 */
declare class PostHogTraceExporter extends OTLPTraceExporter {
    private readonly disabled;
    constructor(options: PostHogTraceExporterOptions);
    export(spans: ReadableSpan[], resultCallback: (result: {
        code: number;
        error?: Error;
    }) => void): void;
}

interface PostHogSpanProcessorOptions {
    /**
     * Your PostHog project token (the `phc_...` key). Required; a blank token disables the
     * processor as a defensive no-op.
     */
    projectToken: string;
    /**
     * PostHog host URL. Defaults to `https://us.i.posthog.com`.
     */
    host?: string;
    /**
     * @internal Injected processor for testing — bypasses exporter creation.
     */
    _spanProcessor?: SpanProcessor;
}
/**
 * An OpenTelemetry `SpanProcessor` that sends AI traces to PostHog.
 *
 * `projectToken` is required; a blank token disables the processor as a defensive no-op.
 *
 * Internally batches spans and exports them to PostHog's OTLP ingestion
 * endpoint. Only AI-related spans (those whose name or attribute keys
 * start with `gen_ai.`, `llm.`, `ai.`, or `traceloop.`) are exported;
 * all other spans are silently dropped.
 *
 * This is the recommended integration point when your setup accepts a
 * `SpanProcessor`. If you need a `TraceExporter` instead (e.g. for
 * Vercel's `registerOTel`), use {@link PostHogTraceExporter}.
 *
 * @example
 * ```ts
 * import { PostHogSpanProcessor } from '@posthog/ai/otel'
 * import { NodeSDK } from '@opentelemetry/sdk-node'
 *
 * const sdk = new NodeSDK({
 *   spanProcessors: [new PostHogSpanProcessor({ projectToken: 'phc_...' })],
 * })
 * sdk.start()
 * ```
 */
declare class PostHogSpanProcessor implements SpanProcessor {
    private readonly inner;
    constructor(options: PostHogSpanProcessorOptions);
    onStart(span: Span, parentContext: Context): void;
    onEnd(span: ReadableSpan): void;
    shutdown(): Promise<void>;
    forceFlush(): Promise<void>;
}

export { PostHogSpanProcessor, type PostHogSpanProcessorOptions, PostHogTraceExporter, type PostHogTraceExporterOptions };