You can open a span using
startTrace(ThreadContext, String, String, Map)
, and stop it using
stopTrace(String)
, at which point the tracing system will queue
the data to be sent somewhere for processing and storage.
You can add additional data to a span using the setAttribute(...)
methods, e.g. setAttribute(String, String, String)
. This allows you
to attach data that is not available when the span is opened.
Implementation node: tracers have similar performance requirements to loggers, in that they may be called in performance-sensitive locations. For example, network requests must be queued on separate threads, in order to avoid blocking any calling threads. Care should be taken to avoid allocating an excessive number of objects.
-
Nested Class Summary
-
Field Summary
-
Method Summary
Modifier and TypeMethodDescriptionvoid
If an exception occurs during a span, you can add data about the exception to the span where the exception occurred.void
Some tracing implementations support the concept of "events" within a span, marking a point in time during the span when something interesting happened.void
setAttribute
(String id, String key, boolean value) Adds a boolean attribute to an active span.void
setAttribute
(String id, String key, double value) Adds a double attribute to an active span.void
setAttribute
(String id, String key, long value) Adds a long attribute to an active span.void
setAttribute
(String id, String key, String value) Adds a String attribute to an active span.void
startTrace
(ThreadContext threadContext, String id, String name, Map<String, Object> attributes) Called when a span starts.void
Called when a span ends.Usually you won't need this about scopes when using tracing.
-
Field Details
-
NOOP
A Tracer implementation that does nothing. This is used when no tracer is configured, in order to avoid null checks everywhere.
-
-
Method Details
-
startTrace
Called when a span starts.- Parameters:
threadContext
- the current context. Required for tracing parent/child span activity.id
- a unique identifier for the activity, and will not be sent to the tracing system. Add the ID to the attributes if it is importantname
- the name of the span. Sent to the tracing systemattributes
- arbitrary key/value data for the span. Sent to the tracing system
-
stopTrace
Called when a span ends.- Parameters:
id
- an identifier for the span
-
addEvent
Some tracing implementations support the concept of "events" within a span, marking a point in time during the span when something interesting happened. If the tracing implementation doesn't support events, then nothing will be recorded. This should only be called when a trace already been started on thetraceable
.- Parameters:
id
- an identifier for the spaneventName
- the event that happened. This should be something meaningful to people reviewing the data, for example "send response", "finished processing", "validated request", etc.
-
addError
If an exception occurs during a span, you can add data about the exception to the span where the exception occurred. This should only be called when a span has been started, otherwise it has no effect.- Parameters:
id
- an identifier for the spanthrowable
- the exception that occurred.
-
setAttribute
Adds a boolean attribute to an active span. These will be sent to the endpoint that collects tracing data.- Parameters:
id
- an identifier for the spankey
- the attribute keyvalue
- the attribute value
-
setAttribute
Adds a double attribute to an active span. These will be sent to the endpoint that collects tracing data.- Parameters:
id
- an identifier for the spankey
- the attribute keyvalue
- the attribute value
-
setAttribute
Adds a long attribute to an active span. These will be sent to the endpoint that collects tracing data.- Parameters:
id
- an identifier for the spankey
- the attribute keyvalue
- the attribute value
-
setAttribute
Adds a String attribute to an active span. These will be sent to the endpoint that collects tracing data.- Parameters:
id
- an identifier for the spankey
- the attribute keyvalue
- the attribute value
-
withScope
Usually you won't need this about scopes when using tracing. However, sometimes you may want more details to be captured about a particular section of code. You can think of "scope" as representing the currently active tracing context. Using scope allows the tracing agent to do the following:- Enables automatic correlation between the "active span" and logging, where logs have also been captured.
- Enables capturing any exceptions thrown when the span is active, and linking those exceptions to the span.
- Allows the sampling profiler to be used as it allows samples to be linked to the active span (if any), so the agent can automatically get extra spans without manual instrumentation.
However, a scope must be closed in the same thread in which it was opened, which cannot be guaranteed when using tasks.
Note that in the OpenTelemetry documentation, spans, scope and context are fairly straightforward to use, since `Scope` is an `AutoCloseable` and so can be easily created and cleaned up use try-with-resources blocks. Unfortunately, Elasticsearch is a complex piece of software, and also extremely asynchronous, so the typical OpenTelemetry examples do not work.
Nonetheless, it is possible to manually use scope where more detail is needed by explicitly opening a scope via the `Tracer`.
- Parameters:
id
- an identifier for the span- Returns:
- a scope. You MUST close it when you are finished with it.
-