Documentation
¶
Overview ¶
Package posthogotel forwards OpenTelemetry AI spans to PostHog AI observability.
It keeps only spans that follow a known AI semantic convention. A span qualifies when its name or any of its attribute keys starts with one of "gen_ai.", "llm.", "ai.", or "traceloop.". Every other span is dropped. Kept spans go over OTLP/HTTP to the PostHog "/i/v0/ai/otel" endpoint with the project API key in an Authorization: Bearer header.
The package offers two integrations:
SpanProcessor is the recommended integration. It filters spans, batches the AI spans, and exports them. Register it with TracerProvider.RegisterSpanProcessor (or the WithSpanProcessor option). It also adds the PostHog request context (see posthog.WithRequestContext) to the AI spans it exports, which Exporter can't.
Exporter is for setups that supply their own span processor, or frameworks that accept only a span exporter. It filters spans and delegates the AI spans to an OTLP/HTTP exporter.
ContextSpanProcessor adds IDs to general application spans without exporting them. NewRequestContextMiddleware also enriches the existing incoming span and limits request IDs to the handler lifetime. These integrations use the application's provider and exporter, and add no IDs when the PostHog client is nil, disabled, or closed.
This is a separate Go module so that the core posthog-go SDK does not depend on OpenTelemetry. This module depends on the core module for the request context.
Index ¶
- Constants
- func EnqueueWithContext(ctx context.Context, client posthog.EnqueueClient, msg posthog.Message) error
- func IsAISpan(span sdktrace.ReadOnlySpan) bool
- func NewRequestContextMiddleware(client posthog.Client, next http.Handler, opts ...posthog.RequestContextOption) http.Handler
- type ContextSpanProcessor
- type Exporter
- type Option
- type SpanProcessor
Constants ¶
const (
// DefaultHost is the PostHog US cloud host used when WithHost is not set.
DefaultHost = "https://us.i.posthog.com"
)
Variables ¶
This section is empty.
Functions ¶
func EnqueueWithContext ¶ added in v1.37.0
func EnqueueWithContext(ctx context.Context, client posthog.EnqueueClient, msg posthog.Message) error
EnqueueWithContext is the opt-in enqueue path for exceptions with OpenTelemetry trace IDs. It keeps event and request-context properties ahead of derived IDs. Other messages use posthog.EnqueueWithContext without trace enrichment.
func IsAISpan ¶
func IsAISpan(span sdktrace.ReadOnlySpan) bool
IsAISpan reports whether a span follows a known AI semantic convention. It returns true when the span name, or any of its attribute keys, starts with one of the aiSpanPrefixes.
func NewRequestContextMiddleware ¶ added in v1.38.0
func NewRequestContextMiddleware(client posthog.Client, next http.Handler, opts ...posthog.RequestContextOption) http.Handler
NewRequestContextMiddleware also enriches the existing request span after header extraction. It adds IDs to spans only while client is enabled, like NewContextSpanProcessor. It accepts the core middleware options. Spans started from an inherited request context after the handler returns omit request IDs. Register ContextSpanProcessor for child spans.
Types ¶
type ContextSpanProcessor ¶ added in v1.38.0
type ContextSpanProcessor struct {
// contains filtered or unexported fields
}
ContextSpanProcessor adds PostHog IDs to spans from the application's provider. Register it before processors that consume attributes in OnStart. It does not export spans.
func NewContextSpanProcessor ¶ added in v1.38.0
func NewContextSpanProcessor(client posthog.Client) *ContextSpanProcessor
NewContextSpanProcessor creates an optional bridge for general application spans. It adds IDs only while client is enabled, so a nil, disabled, or closed client adds none. A client wrapper can implement IsEnabled() bool to report its state; otherwise it counts as enabled.
func (*ContextSpanProcessor) ForceFlush ¶ added in v1.38.0
func (*ContextSpanProcessor) ForceFlush(context.Context) error
func (*ContextSpanProcessor) OnEnd ¶ added in v1.38.0
func (*ContextSpanProcessor) OnEnd(sdktrace.ReadOnlySpan)
func (*ContextSpanProcessor) OnStart ¶ added in v1.38.0
func (p *ContextSpanProcessor) OnStart(ctx context.Context, span sdktrace.ReadWriteSpan)
type Exporter ¶
type Exporter struct {
// contains filtered or unexported fields
}
Exporter is a span exporter that keeps only AI spans and forwards them to PostHog. Use it when you supply your own span processor, or with a framework that accepts only a span exporter. For most setups prefer SpanProcessor. Exporters only see finished spans, so they can't add PostHog request context; use SpanProcessor for that.
func NewExporter ¶
NewExporter builds an Exporter for the given project API key.
func (*Exporter) ExportSpans ¶
ExportSpans forwards the AI spans in the batch and drops the rest. It returns early without a request when the batch has no AI spans.
type Option ¶
type Option func(*config)
Option configures the exporter or the span processor.
func WithHost ¶
WithHost sets the PostHog host, for example "https://eu.i.posthog.com". An empty or blank value keeps DefaultHost.
type SpanProcessor ¶
type SpanProcessor struct {
// contains filtered or unexported fields
}
SpanProcessor is a self-contained span processor that keeps only AI spans, batches them, and exports them to PostHog. Register it with TracerProvider.RegisterSpanProcessor or the sdktrace.WithSpanProcessor option. Spans started from a context carrying posthog.WithRequestContext are exported with its distinct ID, session ID and properties. Other processors on the provider don't see them.
func NewSpanProcessor ¶
NewSpanProcessor builds a SpanProcessor for the given project API key. It wraps a batch span processor around the PostHog OTLP exporter.
func (*SpanProcessor) ForceFlush ¶
func (p *SpanProcessor) ForceFlush(ctx context.Context) error
ForceFlush flushes the pending AI spans through the batch span processor.
func (*SpanProcessor) OnEnd ¶
func (p *SpanProcessor) OnEnd(s sdktrace.ReadOnlySpan)
OnEnd forwards AI spans to the batch processor and drops the rest. A forwarded span is a copy carrying the request context captured in OnStart.
func (*SpanProcessor) OnStart ¶
func (p *SpanProcessor) OnStart(ctx context.Context, s sdktrace.ReadWriteSpan)
OnStart captures the PostHog request context carried by ctx (see posthog.WithRequestContext) for OnEnd. It never changes the live span.