:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
// Derive the adaptive span-summary header (JON-37) from a span's native fields + well-known OTel
// attributes. Every field is optional in the output where the data is — the header renders only
// what resolves and reflows, so a bare internal span shows little and an HTTP-to-k8s span lights up.
import type { Span } from './types'
import { SPAN_KIND_LABELS, STATUS_CODE_LABELS } from './types'
export type SummaryStatusType = 'success' | 'warning' | 'danger' | 'default'
export interface SpanSummary {
/** http method+route if present, else the span name. */
operation: string
/** http status (colored by class) if present, else the OTel status. */
status: { label: string; type: SummaryStatusType }
service: string
/** Callee, if a peer attribute is set — drives the "service → peer" arrow. */
peerService: string | null
durationNano: number
spanId: string
traceId: string
/** Empty for a root span — the header renders the parent link only when set. */
parentSpanId: string | null
/** OTel span kind label (Internal / Server / Client / Producer / Consumer). */
kind: string
timestamp: string
endTimestamp: string
/** HTTP / Database / RPC / Messaging, derived from the attribute namespace; null if unknown. */
type: string | null
cluster: string | null
pod: string | null
}
// new and old semantic-convention spellings, tried in order.
const METHOD_KEYS = ['http.request.method', 'http.method']
const ROUTE_KEYS = ['http.route', 'http.target', 'url.path']
const HTTP_STATUS_KEYS = ['http.response.status_code', 'http.status_code']
// Logical service-identity attributes only — NOT transport-layer addresses like `server.address`
// (a host/IP that any DB/Redis/gRPC client span carries), which would render a misleading
// "service → 10.0.0.5:5432" peer arrow.
const PEER_KEYS = ['peer.service', 'net.peer.name']
function firstAttr(attrs: Record<string, string>, keys: string[]): string | null {
for (const key of keys) {
if (attrs[key]) {
return attrs[key]
}
}
return null
}
function httpStatusType(code: number): SummaryStatusType {
if (code >= 500) {
return 'danger'
}
if (code >= 400) {
return 'warning'
}
if (code >= 200 && code < 300) {
return 'success'
}
return 'default'
}
function deriveType(attrs: Record<string, string>): string | null {
for (const key of Object.keys(attrs)) {
if (key.startsWith('http.') || key.startsWith('url.')) {
return 'HTTP'
}
if (key.startsWith('db.')) {
return 'Database'
}
if (key.startsWith('rpc.')) {
return 'RPC'
}
if (key.startsWith('messaging.')) {
return 'Messaging'
}
}
return null
}
// The query text for a DB span. `db.query.text` is the stabilized OTel DB-semconv key; `db.statement`
// is the long-standing (pre-rename) spelling most deployed instrumentations still emit — check both.
// Usually parameterized (literal values stripped to `?`) by the instrumentation. Null for non-DB spans.
export function getQueryText(span: Span): string | null {
return firstAttr(span.attributes ?? {}, ['db.query.text', 'db.statement'])
}
export function deriveSpanSummary(span: Span): SpanSummary {
const attrs = span.attributes ?? {}
const resourceAttrs = span.resource_attributes ?? {}
const method = firstAttr(attrs, METHOD_KEYS)
const route = firstAttr(attrs, ROUTE_KEYS)
const operation = method ? `${method} ${route ?? ''}`.trim() : span.name
const httpStatus = firstAttr(attrs, HTTP_STATUS_KEYS)
let status: { label: string; type: SummaryStatusType }
if (httpStatus) {
const code = parseInt(httpStatus, 10)
status = { label: httpStatus, type: Number.isNaN(code) ? 'default' : httpStatusType(code) }
} else {
status = STATUS_CODE_LABELS[span.status_code] ?? { label: String(span.status_code), type: 'default' }
}
return {
operation,
status,
service: span.service_name,
peerService: firstAttr(attrs, PEER_KEYS),
durationNano: span.duration_nano,
spanId: span.span_id,
traceId: span.trace_id,
parentSpanId: span.parent_span_id || null,
kind: SPAN_KIND_LABELS[span.kind] ?? String(span.kind),
timestamp: span.timestamp,
endTimestamp: span.end_time,
type: deriveType(attrs),
// k8s.* are OTel *resource* attributes, so read the resource map first; fall back to span
// attributes for collectors that flatten them in. Absent in both → no chip.
cluster: resourceAttrs['k8s.cluster.name'] || attrs['k8s.cluster.name'] || null,
pod: resourceAttrs['k8s.pod.name'] || attrs['k8s.pod.name'] || null,
}
}