Documentation
¶
Overview ¶
Package telemetry is the OpenTelemetry metrics and traces this repository's processes publish.
It follows the fleet's shape: push over OTLP, and only when a collector is named. No process grows a listener for it. Where nothing names a collector, nothing is exported and every instrument records into a no-op, so metrics cost nothing where nobody collects them.
Configuration is OpenTelemetry's own environment, read by its SDK: OTEL_EXPORTER_OTLP_ENDPOINT (or OTEL_EXPORTER_OTLP_METRICS_ENDPOINT), OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, OTEL_METRIC_EXPORT_INTERVAL, OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG, OTEL_SERVICE_NAME and OTEL_RESOURCE_ATTRIBUTES. Nothing here restates it.
Traces carry no personal data, and this package enforces that rather than hoping: see FilterExporter.
Index ¶
- Constants
- Variables
- func ConnectClientOptions() []connect.ClientOption
- func ConnectOptions() []connect.HandlerOption
- func Enabled() bool
- func FilterExporter(next sdktrace.SpanExporter) sdktrace.SpanExporter
- func Flush(ctx context.Context) error
- func HTTPClient(base http.RoundTripper) *http.Client
- func HTTPHandler(h http.Handler, service string) http.Handler
- func ProfileOf(key string) string
- func Start(ctx context.Context, service, version string, log *slog.Logger) (func(context.Context) error, error)
- func TracesEnabled() bool
- type Notary
- type Observe
- type Queue
- type Writer
Constants ¶
const ( AttrTransport = sdktelemetry.AttrTransport AttrDelivery = sdktelemetry.AttrDelivery AttrDurability = sdktelemetry.AttrDurability AttrOutcome = sdktelemetry.AttrOutcome AttrRecords = sdktelemetry.AttrRecords AttrRejected = sdktelemetry.AttrRejected AttrTenant = sdktelemetry.AttrTenant AttrAction = sdktelemetry.AttrAction )
The span attribute names, the allowlist and the Connect interceptors are the SDK's, because an emitter needs them too; they are re-exported here so that the services keep one place to look.
Variables ¶
var SpanAttributeAllowlist = sdktelemetry.SpanAttributeAllowlist
SpanAttributeAllowlist is every attribute a span leaving this process may carry; see the SDK's telemetry package for what it holds and why.
Functions ¶
func ConnectClientOptions ¶ added in v0.6.0
func ConnectClientOptions() []connect.ClientOption
ConnectClientOptions is the same for a client.
func ConnectOptions ¶ added in v0.6.0
func ConnectOptions() []connect.HandlerOption
ConnectOptions instruments a Connect handler: one server span per call.
func Enabled ¶
func Enabled() bool
Enabled reports whether a collector is named in the environment for metrics.
func FilterExporter ¶ added in v0.6.0
func FilterExporter(next sdktrace.SpanExporter) sdktrace.SpanExporter
FilterExporter wraps an exporter so that only SpanAttributeAllowlist leaves the process. Span events (a recorded error's message is one), links' attributes and a status description are removed outright: they are free text.
func Flush ¶ added in v0.7.0
Flush exports whatever the providers Start installed are holding, now. A process that is frozen between invocations (a function platform) cannot wait for the next periodic export, so it flushes before it returns. Without a collector there is nothing to flush.
func HTTPClient ¶ added in v0.6.0
func HTTPClient(base http.RoundTripper) *http.Client
HTTPClient returns a client that propagates the trace to what it calls.
func HTTPHandler ¶ added in v0.6.0
HTTPHandler wraps a server's mux in an HTTP server span, continuing the caller's traceparent. The liveness and readiness probes are left out: a span every few seconds per pod is noise.
func ProfileOf ¶
ProfileOf is the profile an archive key is under, or "" for a key outside the records layout (records/<profile>/...). It is the one label these counters carry: a profile is a handful of names a deployment chose, where a tenant would be thousands.
func Start ¶
func Start(ctx context.Context, service, version string, log *slog.Logger) (func(context.Context) error, error)
Start installs the global meter provider when a collector is named for metrics and the global tracer provider (and the W3C trace-context propagator) when one is named for traces, and returns what flushes and stops them. Without a collector it installs nothing and the returned function does nothing.
func TracesEnabled ¶ added in v0.6.0
func TracesEnabled() bool
TracesEnabled reports whether a collector is named for traces. It is the same rule as for metrics with the traces-specific variable: unset means nothing is exported and the tracer is the SDK's no-op, which costs nothing and cannot fail.
Types ¶
type Notary ¶ added in v0.7.0
type Notary struct {
// contains filtered or unexported fields
}
Notary is what the notary reports.
The notary is a scheduled job, so it pushes what it saw when it last ran and then goes away; the series stops with it. That is why SealAge is read with the time since its last sample added (see AuditSealStale in the chart): a notary that no longer runs shows as an age that keeps climbing and not as a series that disappeared.
func NewNotary ¶ added in v0.7.0
func NewNotary(provider metric.MeterProvider) (*Notary, error)
NewNotary makes the notary's instruments on the given provider, normally the global one Start installed.
type Observe ¶ added in v0.7.0
type Observe struct {
// contains filtered or unexported fields
}
Observe is what the indexer counts.
The one to alert on is Deferred: the archive is fine when it rises, but the index a reader searches is behind it, and nobody notices an index that is quietly behind until it answers wrongly.
func NewObserve ¶ added in v0.7.0
func NewObserve(provider metric.MeterProvider) (*Observe, error)
NewObserve makes the indexer's instruments on the given provider.
func (*Observe) Deferred ¶ added in v0.7.0
Deferred counts one object the indexer did not take. Permanent is an object that will never read and has been skipped; otherwise it is retried.
type Queue ¶ added in v0.7.0
type Queue struct {
// contains filtered or unexported fields
}
Queue is what a process that takes records off a queue reports about the queue: how long a message waited.
The age of a message at receive is the number to watch, and a depth is not: a deep queue that is draining is healthy, and a shallow one whose oldest message is an hour old is not. The depth and the DLQ are the platform's own metrics (CloudWatch's ApproximateAgeOfOldestMessage and ApproximateNumberOfMessagesVisible), and the alarms on them are in deploy/pulumi; this is the per-message view that says whether the writer is keeping up and by how much.
func NewQueue ¶ added in v0.7.0
func NewQueue(provider metric.MeterProvider) (*Queue, error)
NewQueue makes the queue instruments on the given provider, normally the global one Start installed.
type Writer ¶
type Writer struct {
// contains filtered or unexported fields
}
Writer is what the writer counts.
Each instrument answers a question an operator would otherwise have to ask the logs. The writer does not index (observe does, and counts that in Observe); what is worth an alert here is a dead letter.
func NewWriter ¶
func NewWriter(provider metric.MeterProvider) (*Writer, error)
NewWriter makes the writer's instruments on the given provider, normally the global one Start installed.
func (*Writer) DeadLettered ¶
func (w *Writer) DeadLettered()
DeadLettered counts one record the writer could not process.
func (*Writer) DuplicatesLikely ¶
DuplicatesLikely counts records a redelivery would write again.
func (*Writer) MetaDropped ¶
func (w *Writer) MetaDropped()
MetaDropped counts one of the writer's own records that was lost.
func (*Writer) RetentionNotExtended ¶
RetentionNotExtended counts one object an addendum could not lengthen the lock of. The addendum itself is written; what is at risk is the earlier evidence, which keeps its old date until somebody extends it by hand.
func (*Writer) UnknownCatalogue ¶ added in v0.13.0
UnknownCatalogue counts one record refused for naming a catalogue version this writer does not have, by the source and version it names, up to a bounded number of distinct pairs and then as "other".
Source Files