kong.tracing

Tracer module Application-level tracing for Kong.

span:finish(end_time_ns)

Ends a Span Set the end time and release the span, the span table MUST not being used after ended.

Parameters

end_time_ns (number|nil):

Usage

span:finish()

local time = ngx.now()
span:finish(time * 100000000)

span:set_attribute(key, value)

Set an attribute to a Span

Parameters

key (string):
value (string|number|boolean|nil):

Usage

span:set_attribute("net.transport", "ip_tcp")
span:set_attribute("net.peer.port", 443)
span:set_attribute("exception.escaped", true)
span:set_attribute("unset.this", nil)

span:add_event(name, attributes, time_ns)

Adds an event to a Span

Parameters

name (string): Event name
attributes (table|nil): Event attributes
time_ns (number|nil): Event timestamp

span:record_error(err)

Adds an error event to a Span

Parameters

err (string): error string

span:set_status(status)

Adds an error event to a Span Status codes:

0 unset
1 ok
2 error

Parameters

status (number): status code

kong.tracing.active_span()

Get the active span Returns the root span by default

Phases

rewrite, access, header_filter, response, body_filter, log, admin_api

Returns

table: span

kong.tracing.set_active_span(span)

Set the active span

Phases

rewrite, access, header_filter, response, body_filter, log, admin_api

Parameters

span (table):

kong.tracing.start_span(name, options)

Create a new Span

Phases

rewrite, access, header_filter, response, body_filter, log, admin_api

Parameters

name (string): span name
options (table): TODO(mayo)

Returns

table: span

kong.tracing.process_span(processor)

Batch process spans Please note that socket is not available in the log phase, use ngx.timer.at instead

Phases

Parameters

processor (function): a function that accept a span as the parameter

kong.tracing:set_should_sample(should_sample)

Update the value of should_sample for all spans

Parameters

should_sample (bool): value for the sample parameter

kong.tracing:get_sampling_decision(parent_should_sample, sampling_rate)

Get the sampling decision result

Uses a parent-based sampler when the parent has sampled flag == false to inherit the non-recording decision from the parent span, or when trace_id is not available.

Else, apply the probability-based should_sample decision.

Parameters

parent_should_sample (bool): value of the parent span sampled flag extracted from the incoming tracing headers
sampling_rate (number): the sampling rate to apply for the probability sampler

Returns

bool: sampled value of sampled for this trace