Documentation
¶
Overview ¶
Package telemetry provides explicit OpenTelemetry configuration, bounded vocabularies and outbound HTTP measurement.
Design ¶
Config accepts metric/trace providers and defaults to no-op implementations without reading global providers. RoundTripper returns the original transport when unconfigured; otherwise it records bounded method, server, status and error categories. URL paths, query strings, bodies and error messages are excluded from metrics and spans.
Vocabulary maps values outside a fixed set to OtherValue. Consumers own SDKs, exporters, sampling and any slog bridge; the library installs none. Recording fakes in telemetry/telemetrytest let tests inspect emitted attributes and verify that secrets are absent.
References ¶
- Decision record 0040: https://github.com/deploymenttheory/go-apple-dm/blob/main/docs/research/decisions/0040-opentelemetry-seam.md
- Decision record 0037: https://github.com/deploymenttheory/go-apple-dm/blob/main/docs/research/decisions/0037-event-sinks-and-redaction.md
- OpenTelemetry: https://opentelemetry.io/docs/languages/go/libraries/
- OpenTelemetry: https://opentelemetry.io/docs/specs/semconv/http/http-metrics/
- OpenTelemetry: https://opentelemetry.io/docs/specs/otel/versioning-and-stability/
- Apple: https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns
Index ¶
Constants ¶
const ( AttrHTTPRequestMethod = "http.request.method" AttrHTTPResponseStatusCode = "http.response.status_code" AttrServerAddress = "server.address" AttrServerPort = "server.port" AttrErrorType = "error.type" )
Attribute keys used by the HTTP instrumentation. The small fixed set is maintained locally so only reviewed attributes enter emitted telemetry.
const MetricHTTPClientDuration = "http.client.request.duration"
MetricHTTPClientDuration is the stable OpenTelemetry instrument for an outbound request, measured in seconds.
const OtherValue = "_OTHER"
OtherValue replaces any value outside a Vocabulary. It matches the convention OpenTelemetry's own HTTP semantic conventions use for an unrecognised request method, and the leading underscore keeps it from colliding with anything Apple sends.
const ScopeRoot = "github.com/deploymenttheory/go-apple-dm"
ScopeRoot is the module path every instrumentation scope is rooted at.
Variables ¶
This section is empty.
Functions ¶
func RoundTripper ¶
func RoundTripper(next http.RoundTripper, cfg Config, opts ...Option) http.RoundTripper
RoundTripper wraps next with HTTP duration metrics and optional spans. A nil next uses http.DefaultTransport; without providers the transport is returned unwrapped.
Attributes include bounded method, server address/port, status and error category. Paths, queries, bodies and error messages are omitted to limit cardinality and avoid exposing values such as APNs device tokens. Response and error values are returned unchanged.
func Scope ¶
Scope returns the instrumentation scope name for a package, which OpenTelemetry defines as the fully qualified name of the instrumenting library: Scope("dep") is the scope for package dep.
An empty pkg returns ScopeRoot, so a caller that has no sub-package to name still produces a valid scope rather than a trailing slash.
Types ¶
type Config ¶
type Config struct {
// MeterProvider supplies meters. Nil records no metrics.
MeterProvider metric.MeterProvider
// TracerProvider supplies tracers. Nil records no spans.
TracerProvider trace.TracerProvider
}
Config supplies optional metric and trace providers. Nil providers select no-op implementations without reading global OpenTelemetry configuration. Consumers retain ownership of SDKs and exporters.
func (Config) Metrics ¶
Metrics reports whether a consumer asked for metrics. Instrument construction is cheap but not free, so a package that would build many instruments may skip the work entirely.
type Option ¶
type Option func(*rtOptions)
Option configures a RoundTripper.
func WithAttributes ¶
WithAttributes adds constant attributes to every measurement. They must be fixed at configuration time: an attribute whose value varies per request multiplies the series count by its range, and one that varies per device is unbounded.
type Vocabulary ¶
type Vocabulary struct {
// contains filtered or unexported fields
}
Vocabulary is a closed set of values for one metric attribute.
It exists because almost every interesting label on this library's metrics starts life as a string a device sent us: a MessageType, a RequestType, a declaration reason code. A metric attribute built straight from one of those is an unbounded time series that a single malformed or hostile enrollment can grow without limit, and OpenTelemetry's SDK answers that by discarding the overflow into a synthetic series — so the metric stops being trustworthy long before anyone notices.
A Vocabulary is built once from a set fixed at compile time, usually one of the generated registries in schema/, and maps everything else to OtherValue. A caller can then label freely without auditing the call site.
The zero value is not usable; build one with NewVocabulary. A Vocabulary is immutable after construction and safe for concurrent use.
func NewVocabulary ¶
func NewVocabulary(key string, values []string) *Vocabulary
NewVocabulary returns a Vocabulary for an attribute key over a closed set of values. Duplicate values are collapsed; an empty set maps everything to OtherValue, which is a usable if uninformative attribute rather than an error, because a generated registry that turns out to be empty should not take a server down.
func (*Vocabulary) Allows ¶
func (v *Vocabulary) Allows(value string) bool
Allows reports whether a value is in the vocabulary. Use it to decide whether a value is worth putting on a span, where cardinality is not a concern but a fabricated value is still worth knowing about.
func (*Vocabulary) Attr ¶
func (v *Vocabulary) Attr(value string) attribute.KeyValue
Attr returns the attribute for a value, replacing anything outside the vocabulary with OtherValue.
func (*Vocabulary) Cardinality ¶
func (v *Vocabulary) Cardinality() int
Cardinality is the number of series one Vocabulary can produce for its key, which is its size plus OtherValue. A caller multiplying the cardinality of every attribute on an instrument gets that instrument's worst case, which is the number worth checking against a backend's limit before shipping.
func (*Vocabulary) Values ¶
func (v *Vocabulary) Values() []string
Values returns the vocabulary in sorted order, excluding OtherValue. It is a copy: a caller cannot widen the set through it.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package telemetrytest records OpenTelemetry measurements and spans for assertions.
|
Package telemetrytest records OpenTelemetry measurements and spans for assertions. |