Module opentracing.span¶

new (tracer, context, name, start_timestamp)¶

Create new span

Parameters:

• tracer: (table)
• context: (table)
• name: (string)
• start_timestamp: (optional number)

Returns:

(table) span

context (self)¶

Provides access to the SpanContext associated with this Span The SpanContext contains state that propagates from Span to Span in a larger tracer.

Parameters:

• self: (table)

Returns:

(table) context

tracer (self)¶

Provides access to the Tracer that created this span.

Parameters:

• self: (table)

Returns:

(table) tracer the Tracer that created this span.

set_operation_name (self, name)¶

Changes the operation name

Parameters:

• self: (table)
• name: (string)

Returns:

(table) tracer

start_child_span (self, name, start_timestamp)¶

Start child span

Parameters:

• self: (table)
• name: (string)
• start_timestamp: (optional number)

Returns:

(table) child span

finish (self, opts)¶

Indicates the work represented by this Span has completed or terminated.

If finish is called a second time, it is guaranteed to do nothing.

Parameters:

• self: (table)
• opts:
  • finish_timestamp: (number) a timestamp represented by microsecondssince the epoch to mark when the span ended. If unspecified, the currenttime will be used.
  • error: (string) add error tag

Returns:

(boolean) true

Or

(boolean) false

(string) error

set_tag (self, key, value)¶

Attaches a key/value pair to the Span .

The value must be a string, bool, numeric type, or table of such values.

Parameters:

• self: (table)
• key: (string) key or name of the tag. Must be a string.
• value: (any) value of the tag

Returns:

(boolean) true

get_tag (self, key)¶

Get span’s tag

Parameters:

• self: (table)
• key: (string)

Returns:

(any) tag value

each_tag (self)¶

Get tags iterator

Parameters:

• self: (table)

Returns:

(function) iterator

(table) tags

get_tags (self)¶

Get copy of span’s tags

Parameters:

• self: (table)

Returns:

(table) tags

log (self, key, value, timestamp)¶

Log some action

Parameters:

• self: (table)
• key: (table)
• value: (table)
• timestamp: (optional number)

Returns:

(boolean) true

log_kv (self, key_values, timestamp)¶

Attaches a log record to the Span .

Parameters:

• self: (table)
• key_values: (table) a table of string keys and values of string, bool, ornumeric types
• timestamp: (optional number) an optional timestamp as a unix timestamp.defaults to the current time

Returns:

(boolean) true

Usage:¶

span:log_kv({
  ["event"] = "time to first byte",
  ["packet.size"] = packet:size()})

each_log (self)¶

Get span’s logs iterator

Parameters:

• self: (table)

Returns:

(function) log iterator

(table) logs

set_baggage_item (self, key, value)¶

Stores a Baggage item in the Span as a key/value pair.

Enables powerful distributed context propagation functionality where arbitrary application data can be carried along the full path of request execution throughout the system.

Note 1: Baggage is only propagated to the future (recursive) children of this Span .

Note 2: Baggage is sent in-band with every subsequent local and remote calls, so this feature must be used with care.

Parameters:

• self: (table)
• key: (string) Baggage item key
• value: (string) Baggage item value

Returns:

(boolean) true

get_baggage_item (self, key)¶

Retrieves value of the baggage item with the given key.

Parameters:

• self: (table)
• key: (string)

Returns:

(string) value

each_baggage_item (self)¶

Returns an iterator over each attached baggage item

Parameters:

• self: (table)

Returns:

(function) iterator

(table) baggage

set_component (self, component)¶

Set component tag (The software package, framework, library, or module that generated the associated Span.)

Parameters:

• self: (table)
• component: (string)

set_http_method (self, method)¶

Set HTTP method of the request for the associated Span

Parameters:

• self: (table)
• method: (string)

set_http_status_code (self, status_code)¶

Set HTTP response status code for the associated Span

Parameters:

• self: (table)
• status_code: (number)

set_http_url (self, url)¶

Set URL of the request being handled in this segment of the trace, in standard URI format

Parameters:

• self: (table)
• url: (string)

set_http_host (self, host)¶

Set the domain portion of the URL or host header. Used to filter by host as opposed to ip address.

Parameters:

• self: (table)
• host: (string)

set_http_path (self, path)¶

Set the absolute http path, without any query parameters. Used as a filter or to clarify the request path for a given route. For example, the path for a route “/objects/:objectId” could be “/objects/abdc-ff”. This does not limit cardinality like HTTP_ROUTE(“http.route”) can, so is not a good input to a span name.

The Zipkin query api only supports equals filters. Dropping query parameters makes the number of distinct URIs less. For example, one can query for the same resource, regardless of signing parameters encoded in the query line. Dropping query parameters also limits the security impact of this tag.

Parameters:

• self: (table)
• path: (string)

set_http_route (self, route)¶

Set the route which a request matched or “” (empty string) if routing is supported, but there was no match. Unlike HTTP_PATH(“http.path”), this value is fixed cardinality, so is a safe input to a span name function or a metrics dimension. Different formats are possible. For example, the following are all valid route templates: “/users” “/users/:userId” “/users/*”

Route-based span name generation often uses other tags, such as HTTP_METHOD(“http.method”) and HTTP_STATUS_CODE(“http.status_code”). Route-based names can look like “get /users/{userId}”, “post /users”, “get not_found” or “get redirected”.

Parameters:

• self: (table)
• route: (string)

set_http_request_size (self, host)¶

Set the size of the non-empty HTTP request body, in bytes. Large uploads can exceed limits or contribute directly to latency.

Parameters:

• self: (table)
• host: (string)

set_response_size (self, host)¶

Set the size of the non-empty HTTP response body, in bytes. Large downloads can exceed limits or contribute directly to latency.

Parameters:

• self: (table)
• host: (string)

set_peer_address (self, address)¶

Set remote “address”, suitable for use in a networking client library. This may be a “ip:port”, a bare “hostname”, a FQDN, or even a JDBC substring like “mysql://prod-db:3306”

Parameters:

• self: (table)
• address: (string)

set_peer_hostname (self, hostname)¶

Set remote hostname

Parameters:

• self: (table)
• hostname: (string)

set_peer_ipv4 (self, IPv4)¶

Set remote IPv4 address as a .-separated tuple

Parameters:

• self: (table)
• IPv4: (string)

set_peer_ipv6 (self, IPv6)¶

Set remote IPv6 address as a string of colon-separated 4-char hex tuples

Parameters:

• self: (table)
• IPv6: (string)

set_peer_port (self, port)¶

Set remote port

Parameters:

• self: (table)
• port: (number)

set_peer_service (self, service_name)¶

Set remote service name (for some unspecified definition of “service”)

Parameters:

• self: (table)
• service_name: (string)

set_sampling_priority (self, priority)¶

Set sampling priority If greater than 0, a hint to the Tracer to do its best to capture the trace. If 0, a hint to the trace to not-capture the trace. If absent, the Tracer should use its default sampling mechanism.

Parameters:

• self: (table)
• priority: (number)

set_kind (self, kind)¶

Set span’s king Either “client” or “server” for the appropriate roles in an RPC, and “producer” or “consumer” for the appropriate roles in a messaging scenario.

Parameters:

• self: (table)
• kind: (string)

set_client_kind (self)¶

Set client kind to span

Parameters:

• self: (table)

set_server_kind (self)¶

Set server kind to span

Parameters:

• self: (table)

set_producer_kind (self)¶

Set producer kind to span

Parameters:

• self: (table)

set_consumer_kind (self)¶

Set consumer kind to span

Parameters:

• self: (table)