Module org.elasticsearch.server
Package org.elasticsearch.telemetry.tracing

Interface Tracer

public interface Tracer
Represents a distributed tracing system that keeps track of the start and end of various activities in the cluster. Traces are composed of "spans", each of which represents some piece of work with a duration. Spans are nested to create a parent-child hierarchy.

You can open a span using startTrace(org.elasticsearch.telemetry.tracing.TraceContext, org.elasticsearch.telemetry.tracing.Traceable, java.lang.String, java.util.Map<java.lang.String, java.lang.Object>), and stop it using stopTrace(org.elasticsearch.telemetry.tracing.Traceable), 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. 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.

  • Field Details

    • NOOP

      static final Tracer 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

      void startTrace(TraceContext traceContext, Traceable traceable, String name, Map<String,Object> attributes)
      Called when a span starts.
      Parameters:
      traceContext - the current context. Required for tracing parent/child span activity.
      traceable - provides a unique identifier for the activity, and will not be sent to the tracing system. Add the ID to the attributes if it is important
      name - the name of the span. Used to filter out spans, but also sent to the tracing system
      attributes - arbitrary key/value data for the span. Sent to the tracing system

    • startTrace

      void startTrace(String name, Map<String,Object> attributes)
      Called when a span starts. This version of the method relies on context to assign the span a parent.
      Parameters:
      name - the name of the span. Sent to the tracing system

    • stopTrace

      void stopTrace(Traceable traceable)
      Called when a span ends.
      Parameters:
      traceable - provides an identifier for the span

    • stopTrace

      void stopTrace()
      Called when a span ends. This version of the method relies on context to select the span to stop.

    • addEvent

      void addEvent(Traceable traceable, String eventName)
      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 the traceable.
      Parameters:
      traceable - provides an identifier for the span
      eventName - the event that happened. This should be something meaningful to people reviewing the data, for example "send response", "finished processing", "validated request", etc.

    • addError

      void addError(Traceable traceable, Throwable throwable)
      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:
      traceable - provides an identifier for the span
      throwable - the exception that occurred.

    • setAttribute

      void setAttribute(Traceable traceable, String key, boolean value)
      Adds a boolean attribute to an active span. These will be sent to the endpoint that collects tracing data.
      Parameters:
      traceable - provides an identifier for the span
      key - the attribute key
      value - the attribute value

    • setAttribute

      void setAttribute(Traceable traceable, String key, double value)
      Adds a double attribute to an active span. These will be sent to the endpoint that collects tracing data.
      Parameters:
      traceable - provides an identifier for the span
      key - the attribute key
      value - the attribute value

    • setAttribute

      void setAttribute(Traceable traceable, String key, long value)
      Adds a long attribute to an active span. These will be sent to the endpoint that collects tracing data.
      Parameters:
      traceable - provides an identifier for the span
      key - the attribute key
      value - the attribute value

    • setAttribute

      void setAttribute(Traceable traceable, String key, String value)
      Adds a String attribute to an active span. These will be sent to the endpoint that collects tracing data.
      Parameters:
      traceable - provides an identifier for the span
      key - the attribute key
      value - the attribute value

    • withScope

      Releasable withScope(Traceable traceable)
      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:
      traceable - provides an identifier for the span
      Returns:
      a scope. You MUST close it when you are finished with it.