Documentation
¶
Overview ¶
Package otlp exports metrics and request spans to any OpenTelemetry Collector via the OTLP/HTTP JSON protocol (POST /v1/metrics, /v1/traces). No SDK dependency — plain net/http and encoding/json keep the binary self-contained. Extracted from package main's otlp.go / otlp_traces.go per a recorded ADR-0002-style design (post-program extraction).
The package owns the transport (push loops, SSRF-guarded client, endpoint validation) and the OTLP JSON schema. What each METRIC contains is the caller's business: package main wires a snapshot func into NewMetrics that reads its stat singletons and returns []Metric — the engine never imports main's state.
Index ¶
- func ParseTraceparent(tp string) (traceID, spanID string)
- type AnyValue
- type ExportRequest
- type Gauge
- type Hist
- type HistDataPoint
- type KeyValue
- type Metric
- type MetricsExporter
- type NumberDataPoint
- type Resource
- type ResourceMetrics
- type Scope
- type ScopeMetric
- type SnapshotFunc
- type SpanExporter
- type SpanRecord
- type Sum
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ParseTraceparent ¶
ParseTraceparent extracts the trace-id and span-id from a W3C Traceparent header value: "00-{traceID}-{spanID}-{flags}"
Types ¶
type AnyValue ¶
type AnyValue struct {
StringValue string `json:"stringValue,omitempty"`
}
AnyValue is an attribute value (string-only — all Culvert attributes are strings).
type ExportRequest ¶
type ExportRequest struct {
ResourceMetrics []ResourceMetrics `json:"resourceMetrics"`
}
ExportRequest is the top-level /v1/metrics payload.
func Envelope ¶
func Envelope(metrics []Metric) ExportRequest
Envelope wraps a metric set in the standard Culvert resource/scope envelope. Exported so main's payload tests can assert the full shape.
type Gauge ¶
type Gauge struct {
DataPoints []NumberDataPoint `json:"dataPoints"`
}
Gauge is a point-in-time value.
type Hist ¶
type Hist struct {
DataPoints []HistDataPoint `json:"dataPoints"`
AggregationTemporality int `json:"aggregationTemporality"`
}
Hist is a cumulative histogram.
type HistDataPoint ¶
type HistDataPoint struct {
TimeUnixNano string `json:"timeUnixNano"`
Count int64 `json:"count,string"`
Sum float64 `json:"sum"`
BucketCounts []string `json:"bucketCounts"`
ExplicitBounds []float64 `json:"explicitBounds"`
}
HistDataPoint is one histogram sample.
type Metric ¶
type Metric struct {
Name string `json:"name"`
Description string `json:"description,omitempty"`
Unit string `json:"unit,omitempty"`
Sum *Sum `json:"sum,omitempty"`
Gauge *Gauge `json:"gauge,omitempty"`
Histogram *Hist `json:"histogram,omitempty"`
}
Metric is one named metric with exactly one of Sum/Gauge/Histogram set.
type MetricsExporter ¶
type MetricsExporter struct {
// contains filtered or unexported fields
}
MetricsExporter pushes metrics to an OTLP/HTTP endpoint.
func NewMetrics ¶
func NewMetrics(snapshot SnapshotFunc) *MetricsExporter
NewMetrics builds a metrics exporter over the given snapshot source (nil = export an empty metric set; useful for tests).
func (*MetricsExporter) Configure ¶
func (o *MetricsExporter) Configure(endpoint string, headers map[string]string)
Configure sets the OTLP endpoint and starts the push loop.
func (*MetricsExporter) Enabled ¶
func (o *MetricsExporter) Enabled() bool
Enabled returns whether OTLP export is active.
func (*MetricsExporter) Endpoint ¶
func (o *MetricsExporter) Endpoint() string
Endpoint returns the current endpoint URL.
func (*MetricsExporter) Headers ¶
func (o *MetricsExporter) Headers() map[string]string
Headers returns a copy of the configured custom headers (nil when none).
type NumberDataPoint ¶
type NumberDataPoint struct {
Attributes []KeyValue `json:"attributes,omitempty"`
TimeUnixNano string `json:"timeUnixNano"`
AsInt *int64 `json:"asInt,omitempty"`
AsDouble *float64 `json:"asDouble,omitempty"`
}
NumberDataPoint is one numeric sample.
type Resource ¶
type Resource struct {
Attributes []KeyValue `json:"attributes"`
}
Resource carries the resource-identifying attributes.
type ResourceMetrics ¶
type ResourceMetrics struct {
Resource Resource `json:"resource"`
ScopeMetrics []ScopeMetric `json:"scopeMetrics"`
}
ResourceMetrics groups metrics under one resource.
type ScopeMetric ¶
ScopeMetric groups metrics under one instrumentation scope.
type SnapshotFunc ¶
SnapshotFunc returns the current metric set, stamped with the given UnixNano timestamp string. package main's implementation reads the culvert_* stat singletons.
type SpanExporter ¶
type SpanExporter struct {
// contains filtered or unexported fields
}
SpanExporter collects spans and pushes them to an OTLP/HTTP endpoint.
func (*SpanExporter) Configure ¶
func (e *SpanExporter) Configure(endpoint string, headers map[string]string)
Configure sets the OTLP endpoint and starts the push loop.
func (*SpanExporter) Enabled ¶
func (e *SpanExporter) Enabled() bool
Enabled returns whether trace export is active (lock-free fast path).
func (*SpanExporter) RecordSpan ¶
func (e *SpanExporter) RecordSpan(s SpanRecord)
RecordSpan appends a span to the ring buffer. Callers should check Enabled() first to avoid constructing the SpanRecord at all when tracing is off.
func (*SpanExporter) Stop ¶
func (e *SpanExporter) Stop()
Stop halts the push loop and clears the endpoint.
type SpanRecord ¶
type SpanRecord struct {
TraceID string // 32 hex chars from Traceparent
SpanID string // 16 hex chars from Traceparent
Name string // "proxy_request"
Method string // GET, CONNECT, etc.
Host string // target host
Status string // OK, BLOCKED, FILE_BLOCKED, etc.
Rule string // matched policy rule name (may be empty)
ClientIP string // net.SplitHostPort(r.RemoteAddr)
SSLAction string // "inspect", "bypass", or ""
StartNano int64 // time.Now().UnixNano() at request start
EndNano int64 // time.Now().UnixNano() at request end
}
SpanRecord holds the data collected per proxied request. Allocated on the stack in handleRequest and copied into the ring buffer — no heap escape for the common no-OTLP case because RecordSpan callers check Enabled() first.
type Sum ¶
type Sum struct {
DataPoints []NumberDataPoint `json:"dataPoints"`
AggregationTemporality int `json:"aggregationTemporality"` // 2 = cumulative
IsMonotonic bool `json:"isMonotonic"`
}
Sum is a monotonic or non-monotonic cumulative counter.