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 Handler(opts Options) http.Handler
- func HandlerFor(tracer *Tracer) http.Handler
- func Mount(r Router, opts Options) 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 TracingMiddleware(opts Options) func(http.Handler) http.Handler
- func ValidID(id string) bool
- 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 HTTPInfo
- type HostStat
- type Kind
- type Memory
- type MemoryUse
- 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 PoolEstimate
- type Recorder
- type Router
- type Sampler
- type Snapshot
- type Span
- type State
- type StateDuration
- type Statistic
- type Stats
- 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. BackgroundHost = oida.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 HandlerFor ¶
HandlerFor returns the debug front end handler of one tracer.
func Mount ¶
Mount registers the debug front end on r under Options.Path, wired to the tracer resolved from opts.
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 have none, so they group under BackgroundHost.
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 TracingMiddleware ¶
TracingMiddleware returns middleware recording every sampled request into the tracer resolved from opts.
func ValidID ¶
ValidID reports whether id looks like a recorded trace identifier. It keeps hostile input out of lookups and out of rendered links.
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 PoolEstimate ¶
type PoolEstimate = oida.PoolEstimate
PoolEstimate is a heuristic concurrency estimate.
type Router ¶
Router is the subset of a router needed to mount the debug front end. It is satisfied by chi.Router, which is what platform.Router is.
type Sampler ¶
Sampler decides whether a request is traced.
func NewRateSampler ¶
NewRateSampler returns a sampler tracing the given fraction of requests.
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 StateDuration ¶
type StateDuration = oida.StateDuration
StateDuration is the lifetime trace time observed in one state.
type Storage ¶
Storage retains completed traces.
func NewStorageDisk ¶
NewStorageDisk returns storage retaining at most limit traces as JSON documents, so they survive a restart.
func NewStorageMemory ¶
NewStorageMemory returns in-memory storage retaining size traces.
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.
type Tracer ¶
Tracer records traces and backs the debug front end.
func Configure ¶
Configure replaces the process wide tracer with one built from opts and returns it.
func Default ¶
func Default() *Tracer
Default returns the process wide tracer, creating it on first use.
Source Files