Documentation
¶
Overview ¶
Package otel traces a Celerity application with OpenTelemetry.
It is selected by importing it, which `celerity-go generate --telemetry otel` writes:
import _ "github.com/newstack-cloud/celerity-go-sdk/telemetry/otel"
An init installs the tracer, so the generated file is a blank import rather than wiring, and nothing else in an application changes, the spans a dispatch and a resource operation produce are core's, and this only decides where they go.
A module of its own ¶
go.opentelemetry.io is a large dependency, and on a serverless platform a cold start cost rather than only a disk one, so an application that exports no traces does not compile it in. Core declares the seam this implements and depends on no tracing library at all.
What a deployment configures ¶
Where CELERITY_TELEMETRY_ENABLED is true this builds a provider: an OTLP exporter to the collector the environment names, the service named in every span, W3C propagation and X-Ray's alongside it on AWS. ReadSettings is the whole of what it reads, and the defaults are the ones the other SDKs use, so one deployment configures every language alike. Where it is not true nothing is built and the application traces to OpenTelemetry's no-op.
Configuring it yourself ¶
An application that wants something else, a sampler of its own or an exporter this does not build, installs its provider with the OpenTelemetry SDK in the ordinary way and will override the default. The tracer resolves the provider per call rather than capturing one, and an init runs before main does. Pair it with telemetry.SetFlusher so that a shutdown hands over what it is holding.
Index ¶
Constants ¶
const ( // EnabledEnvVar turns exporting on. Anything but true leaves the // application tracing to OpenTelemetry's no-op, which costs a call rather // than a branch at every span. EnabledEnvVar = "CELERITY_TELEMETRY_ENABLED" // EndpointEnvVar is OpenTelemetry's own name for where to export to. EndpointEnvVar = "OTEL_EXPORTER_OTLP_ENDPOINT" // CelerityEndpointEnvVar is what a Celerity deployment sets instead. CelerityEndpointEnvVar = "CELERITY_TRACE_OTLP_COLLECTOR_ENDPOINT" // ServiceNameEnvVar names the application in the traces it produces. ServiceNameEnvVar = "OTEL_SERVICE_NAME" // ServiceVersionEnvVar is the version recorded alongside the name. ServiceVersionEnvVar = "OTEL_SERVICE_VERSION" )
Environment variables telemetry is configured with.
OpenTelemetry's own are read first and Celerity's are the fallback, so an operator who knows OpenTelemetry configures this the way they would configure anything else, and a Celerity deployment that knows nothing about the application still points it at the right collector. The same names and the same order the other SDKs read, so one deployment configures every language alike.
const ( // DefaultEndpoint is the collector a development session runs. DefaultEndpoint = "http://otelcollector:4317" // DefaultServiceName is what an application is called where it says // nothing, which is better than a trace of unnamed spans. DefaultServiceName = "celerity-app" // DefaultServiceVersion is what is recorded where a build stamped none. DefaultServiceVersion = "0.0.0" )
Defaults for what a deployment did not say.
Variables ¶
This section is empty.
Functions ¶
func Configure ¶
Configure builds a tracer provider from what the environment asked for and installs it, along with the propagators and the flusher that goes with it.
Reports whether it installed one. Where the environment did not ask for exporting there is nothing to install, which is the ordinary case for an application that doesn't trace anything, OpenTelemetry's own no-op answers instead.
An application that wants its provider built differently does not have to avoid this. Whatever it installs afterwards wins, because the tracer resolves the provider per call rather than capturing one, and `init` runs before `main` does. Installing its own telemetry.SetFlusher alongside is what makes a shutdown flush what it built.
Types ¶
type Settings ¶
type Settings struct {
// Enabled reports whether an exporter is configured at all.
Enabled bool
// Endpoint is the collector to export to.
Endpoint string
// ServiceName and ServiceVersion name the application in its traces.
ServiceName string
ServiceVersion string
// AWS reports whether the platform is one whose tracing has an identifier
// format of its own, which decides the propagator and the id generator.
AWS bool
}
Settings is what the environment asked for.
func ReadSettings ¶
func ReadSettings() Settings
ReadSettings resolves the settings from the environment.
Exported so that a test, or an application building a provider of its own, can read what a deployment asked for rather than reading the variables again and disagreeing about the defaults.
Source Files