Documentation
¶
Overview ¶
Package telemetry wires the OpenTelemetry SDK into Kargo's long-running components. Setup is called once at startup by each component; code that records spans uses the OpenTelemetry API directly and works whether or not Setup was ever called, since the API's no-op implementations are in effect until it is.
Index ¶
Constants ¶
const ( // ProjectKey is the attribute under which the name of the Kargo Project // (i.e. Kubernetes namespace) a span concerns is recorded. ProjectKey = attribute.Key("kargo.project") // ShardKey is the attribute under which the name of a controller's shard // is recorded. ShardKey = attribute.Key("kargo.shard") // DefaultControllerKey is the attribute under which whether a controller // is the default controller, i.e. the one responsible for resources not // assigned to a specific shard, is recorded. A controller with no shard // name is always the default controller; one with a shard name is the // default controller only if explicitly designated as such. DefaultControllerKey = attribute.Key("kargo.controller.default") // StageKey is the attribute under which the name of a Stage is recorded. StageKey = attribute.Key("kargo.stage") // WarehouseKey is the attribute under which the name of a Warehouse is // recorded. WarehouseKey = attribute.Key("kargo.warehouse") // PromotionKey is the attribute under which the name of a Promotion is // recorded. PromotionKey = attribute.Key("kargo.promotion") // PromotionRequestKey is the attribute under which the name of a // PromotionRequest is recorded. PromotionRequestKey = attribute.Key("kargo.promotion_request") // StepAliasKey is the attribute under which a promotion step's alias is // recorded. StepAliasKey = attribute.Key("kargo.promotion.step.alias") // StepKindKey is the attribute under which a promotion step's kind is // recorded, e.g. "git-clone". StepKindKey = attribute.Key("kargo.promotion.step.kind") // StepStatusKey is the attribute under which the status a promotion step // finished in is recorded. StepStatusKey = attribute.Key("kargo.promotion.step.status") )
Attribute keys shared by Kargo's spans. Keeping them here, rather than spelled out at each call site, keeps the attributes consistent so that they can be queried across components.
Variables ¶
This section is empty.
Functions ¶
func SetupFromEnv ¶
func SetupFromEnv( ctx context.Context, component string, attrs ...attribute.KeyValue, ) (func(), error)
SetupFromEnv configures tracing for the named Kargo component (for example "controller", which is reported as the service "kargo-controller") according to the environment, and returns a function that flushes and shuts tracing down. That function is meant to be deferred by the component's entry point: it never fails, and a problem flushing at shutdown is logged instead. When tracing is disabled, both this function and the one it returns are no-ops.
Any attrs are attached to the component's resource, in addition to its service name and version.
Types ¶
type Config ¶
type Config struct {
// Enabled indicates whether traces are exported at all. When false, the
// OpenTelemetry API's no-op implementations remain in place and the
// instrumentation throughout Kargo costs next to nothing.
Enabled bool `envconfig:"TRACING_ENABLED" default:"false"`
// Protocol is the OTLP transport used for all signals unless overridden for
// a specific signal. The Go exporters do not read this environment variable
// themselves, so it is handled here.
Protocol Protocol `envconfig:"OTEL_EXPORTER_OTLP_PROTOCOL" default:"http/protobuf"`
// TracesProtocol, when set, overrides Protocol for traces specifically.
TracesProtocol Protocol `envconfig:"OTEL_EXPORTER_OTLP_TRACES_PROTOCOL"`
}
Config represents configuration for a component's telemetry. Apart from the Kargo-specific on/off switch, it is deliberately minimal: the OpenTelemetry SDK and exporters configure themselves from the standard OTEL_* environment variables (OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, OTEL_TRACES_SAMPLER, OTEL_RESOURCE_ATTRIBUTES, and so on), and this package intentionally does not duplicate them.
func ConfigFromEnv ¶
func ConfigFromEnv() Config
ConfigFromEnv returns a Config populated from environment variables.
func (Config) EffectiveTracesProtocol ¶
EffectiveTracesProtocol returns the Protocol to use for exporting traces: TracesProtocol if set, otherwise Protocol.
type Protocol ¶
type Protocol string
Protocol identifies the transport used to export telemetry over OTLP.
type Service ¶
type Service struct {
// Name is the logical name of the component, e.g. "kargo-controller". It
// becomes the service.name resource attribute unless OTEL_SERVICE_NAME
// overrides it.
Name string
// Version is the version of Kargo the component is running.
Version string
// Attributes are any additional resource attributes to attach.
Attributes []attribute.KeyValue
}
Service describes the component whose telemetry is being set up. Its fields become resource attributes on every span the component exports.
type ShutdownFunc ¶
ShutdownFunc flushes any telemetry not yet exported and releases the resources held by the SDK. It should be called once, at shutdown.
func Setup ¶
Setup configures the global OpenTelemetry tracer provider and propagators according to cfg and returns a ShutdownFunc. When tracing is disabled, the global no-op implementations are left in place and the returned ShutdownFunc does nothing.
The exporter is configured from the standard OTEL_EXPORTER_OTLP_* environment variables, the sampler from OTEL_TRACES_SAMPLER and OTEL_TRACES_SAMPLER_ARG, and additional resource attributes from OTEL_RESOURCE_ATTRIBUTES.
Source Files