Documentation
¶
Overview ¶
Package telemetry binds github.com/titpetric/oida into the phpscript namespace: traces and spans recorded in process, with a server side rendered front end mounted at /debug/oida.
This is the only package in phpscript that imports oida. Everything else instruments through the symbols bound here, so no call site names the provider. The bindings are type aliases and thin wrappers, so a *telemetry.Span is a *oida.Span: nothing is copied or adapted at runtime.
That covers the call sites, not the whole dependency. The recorder and the front end belong to the host platform, which names oida itself, so replacing the provider means replacing it there as well. A host hands over the tracer that platform built:
var recorder *platform.TelemetryModule
if svc.Find(&recorder) {
module = telemetry.NewModule(recorder.Tracer())
}
The module is a runner.Observer, so a Runtime handed to it reports its scoreboard state and its spans onto the trace of the request that is running:
rt.SetContext(r.Context()) rt.Observe(module)
Instrumentation is nil safe. Spans started without a trace in the context, or in a process where telemetry is disabled, return a nil span whose methods do nothing, so instrumented code runs unchanged either way.
Index ¶
- Constants
- Variables
- func Do(ctx context.Context, name string, fn func(context.Context) error, kind ...Kind) error
- func Mount(r Router, tracer *Tracer) error
- func Recordable(err error) bool
- func SpanSource(ctx context.Context) (string, int)
- func TraceHost(trace Trace) string
- func TraceID(ctx context.Context) string
- func WithSpanFilename(ctx context.Context, filename string) context.Context
- func WithSpanLine(ctx context.Context, line int) context.Context
- func WithTrace(ctx context.Context, t *Trace) context.Context
- type Attributes
- type Kind
- type Module
- func (m *Module) Snapshot() Snapshot
- func (m *Module) Trace(ctx context.Context, message string, kind ...Kind) *Span
- func (m *Module) Tracer() *Tracer
- func (m *Module) TrackLifecycle(ctx context.Context, name, filename string, run func(context.Context) error) error
- func (m *Module) UpdateFilename(ctx context.Context, filename string)
- func (m *Module) UpdateIncludedFiles(ctx context.Context, count int)
- func (m *Module) UpdateStatus(ctx context.Context, state State)
- type Options
- type Router
- type Sampler
- type Snapshot
- type Span
- type State
- type Storage
- type Trace
- type Tracer
Constants ¶
const ( KindInternal = oida.KindInternal KindHTTP = oida.KindHTTP KindDatabase = oida.KindDatabase KindExternal = oida.KindExternal KindTemplate = oida.KindTemplate KindCache = oida.KindCache KindQueue = oida.KindQueue )
Span kinds. The set is open: an unrecognized value is valid, which is what lets PHP pass a plain string.
const ( StateWaiting = oida.StateWaiting StateStarting = oida.StateStarting StateReading = oida.StateReading StateProcessing = oida.StateProcessing StateWriting = oida.StateWriting StateKeepalive = oida.StateKeepalive StateClosing = oida.StateClosing StateError = oida.StateError )
Scoreboard states of a trace in flight. The one-character values follow the convention used by servers such as lighttpd.
const ( // DefaultPath is the mount path of the debug front end. DefaultPath = oida.DefaultPath // RequestIDHeader carries the trace identifier on the request and the // response. RequestIDHeader = oida.RequestIDHeader // BackgroundHost is the host label of traces that did not arrive over the // network: startup steps, cron ticks, queue consumers. oida stopped // re-exporting it from its root package; the constant itself is still the // recorded data's, so this reads it from model rather than inventing a // second label for the same group. BackgroundHost = model.BackgroundHost )
Variables ¶
var ( ErrNilRouter = oida.ErrNilRouter ErrInvalidOptions = oida.ErrInvalidOptions ErrInvalidPath = oida.ErrInvalidPath ErrInvalidSampleRate = oida.ErrInvalidSampleRate ErrTraceNotFound = oida.ErrTraceNotFound ErrDisabled = oida.ErrDisabled )
Recording and configuration failures. Every configuration failure wraps ErrInvalidOptions.
Functions ¶
func Do ¶
Do runs fn inside a span, records the returned error on it and ends it. The error is returned unchanged.
func Mount ¶
Mount registers the debug front end on r under Options.Path, serving the traces of that tracer. oida takes the tracer itself now, there being no process wide one to resolve from options.
func Recordable ¶ added in v0.3.1
Recordable reports whether an error is worth failing a span over. A query that found no rows and a request the client hung up on are control flow, not failures, and marking them would fail the trace and the recorded SLA with it.
It is the shared answer to a question every traced binding asks, so that a cache miss and a canceled request read the same way on the front end whether they came from a query or from session storage.
func SpanSource ¶
SpanSource returns the source location carried by ctx. Both results are zero when no PHP frame published one.
func TraceHost ¶
TraceHost returns the host a trace belongs to. Background traces did not arrive over the network and have no host, so they group under BackgroundHost. oida dropped the function along with the rest of its view model; the grouping is still what the server's own reporting reads by, so it is stated here rather than at each caller.
func TraceID ¶
TraceID returns the identifier of the trace in ctx, or an empty string. It is the value of the Request-Id header for HTTP traces, which makes it the cheapest correlation key for logs.
func WithSpanFilename ¶
WithSpanFilename associates spans started from ctx with a source file.
func WithSpanLine ¶
WithSpanLine associates spans started from ctx with a source line.
Types ¶
type Attributes ¶
type Attributes = oida.Attributes
Attributes is a set of key/value pairs recorded on a span.
type Module ¶
type Module struct {
// contains filtered or unexported fields
}
Module observes the PHP interpreter and records what it reports onto the trace of the request that is running: the scoreboard state, the entrypoint it resolved to, and one span per include, call or template.
It is not a recorder. The host platform registers one, and the tracing middleware that recorder installs is what puts a trace in the request context; this type only writes onto it. That is why interpreter work shows up on the platform's debug front end without phpscript mounting one.
func NewModule ¶
NewModule returns an observer recording into tracer, which is the tracer the host recorder built. A nil tracer is valid and means nothing is recorded: every call below is nil safe, so instrumented code runs unchanged either way.
func (*Module) Trace ¶
Trace implements runner.Observer: it records one span of interpreter work, such as an include, a call or a template, on the running trace.
func (*Module) TrackLifecycle ¶
func (m *Module) TrackLifecycle(ctx context.Context, name, filename string, run func(context.Context) error) error
TrackLifecycle records work that did not arrive over the network, such as a @startup file, as a trace of its own. There is no request to record onto, so this is the one place the observer starts a trace rather than writing to one.
func (*Module) UpdateFilename ¶
UpdateFilename records the PHP entrypoint of the running request. Included files do not replace it: the entrypoint is the file the request resolved to.
func (*Module) UpdateIncludedFiles ¶
UpdateIncludedFiles records how many files the request included beyond its entrypoint.
type Options ¶
Options configures recording, the middleware and the debug front end.
func NewOptions ¶
NewOptions returns the default options for a service of that name, which the front end displays and every trace records. oida applies the OIDA_* environment to options built this way, so a deployment still configures itself; options built as a literal read none.
type Router ¶
Router is the subset of a router needed to mount the debug front end, satisfied by chi.Router, which is what platform.Router is.
type Span ¶
Span is one timed operation within a trace. Every method tolerates a nil receiver.
func SpanFromContext ¶
SpanFromContext returns the innermost span in ctx, or nil.
type Storage ¶
Storage retains completed traces.
func NewStorageDisk ¶
NewStorageDisk returns storage retaining at most limit traces as JSON documents, so they survive a restart.
This is the one place phpscript names an oida sub-package. oida selects a driver from OIDA_STORAGE_DRIVER and the OIDA_STORAGE_* variables, and the telemetry block in a site's configuration is what phpscript configures a site by; reaching the constructor directly is what keeps `driver: disk` meaning what it says instead of moving that choice into the environment.
type Trace ¶
Trace is one recorded unit of work: an HTTP request, a startup step or a background job.
func TraceFromContext ¶
TraceFromContext returns the trace in ctx, or nil.
Source Files