Package io.opentelemetry.api

Class GlobalOpenTelemetry

java.lang.Object
io.opentelemetry.api.GlobalOpenTelemetry
public final class GlobalOpenTelemetry extends Object
Provides access to a global singleton OpenTelemetry instance.

WARNING: To avoid inherent complications around initialization ordering, it's best-practice to pass around instances of OpenTelemetry rather than using GlobalOpenTelemetry. However, the OpenTelemetry javagent makes the OpenTelemetry instance it installs available via GlobalOpenTelemetry. As a result, GlobalOpenTelemetry plays an important role in native instrumentation and application custom instrumentation.

Native instrumentation should use getOrNoop() as the default OpenTelemetry instance, and expose APIs for setting a custom instance. This results in the following behavior:

  • If the OpenTelemetry javaagent is installed, the native instrumentation will default to the OpenTelemetry it installs.
  • If the OpenTelemetry javaagent is not installed, the native instrumentation will default to a noop instance.
  • If the user explicitly sets a custom instance, it will be used, regardless of whether or not the OpenTelemetry javaagent is installed.

Applications with custom instrumentation should call isSet() once during initialization to access the javaagent instance or initialize (e.g. isSet() ? GlobalOpenTelemetry.get() : initializeSdk()), and pass the resulting instance around manually (or with dependency injection) to install custom instrumentation. This results in the following behavior:

  • If the OpenTelemetry javaagent is installed, custom instrumentation will use the OpenTelemetry it installs.
  • If the OpenTelemetry javaagent is not installed, custom instrumentation will use an OpenTelemetry instance initialized by the application.

  • Method Details

    • getOrNoop

      public static OpenTelemetry getOrNoop()
      Returns the registered global OpenTelemetry if set, or else OpenTelemetry.noop().

      NOTE: if the global instance is set, the response is obfuscated to prevent callers from casting to SDK implementation instances and inappropriately accessing non-instrumentation APIs.

      NOTE: This does not result in the set(OpenTelemetry) side effects of get().

      Native instrumentation should use this method to initialize their default OpenTelemetry instance. See class javadoc for more details.

      Since:
      1.57.0

    • isSet

      public static boolean isSet()
      Returns true if GlobalOpenTelemetry is set, otherwise false.

      Application custom instrumentation should use this method during initialization. See class javadoc for more details.

      Since:
      1.57.0

    • get

      public static OpenTelemetry get()
      Returns the registered global OpenTelemetry if set, else calls set(OpenTelemetry) with a no-op OpenTelemetry instance and returns that.

      NOTE: all returned instanced are obfuscated to prevent callers from casting to SDK implementation instances and inappropriately accessing non-instrumentation APIs.

      Native instrumentations should use getOrNoop() instead. See class javadoc for more details.

      Application custom instrumentation should use isSet() and only call this if the response is true. See class javadoc for more details.

      If the global instance has not been set, and io.opentelemetry:opentelemetry-sdk-extension-autoconfigure is present, and "otel.java.global-autoconfigure.enabled" is true, the global instance will be set to an autoconfigured instance instead of OpenTelemetry.noop().

      Throws:
      IllegalStateException - if autoconfigure initialization is triggered and fails.

    • set

      public static void set(OpenTelemetry openTelemetry)
      Sets the OpenTelemetry that should be the global instance. Future calls to get() will return the provided OpenTelemetry instance. This should be called once as early as possible in your application initialization logic, often in a static block in your main class. It should only be called once - an attempt to call it a second time will result in an error. If trying to set the global OpenTelemetry multiple times in tests, use resetForTest() between them.

      If you are using the OpenTelemetry SDK, you should generally use OpenTelemetrySdk.builder().buildAndRegisterGlobal() instead of calling this method directly.

    • set

      public static void set(Supplier<OpenTelemetry> supplier)
      Sets the OpenTelemetry that should be the global instance.

      This method calls the given supplier and calls set(OpenTelemetry), all while holding the GlobalOpenTelemetry mutex.

      Since:
      1.52.0

    • getTracerProvider

      public static TracerProvider getTracerProvider()
      Returns the globally registered TracerProvider.

    • getTracer

      public static Tracer getTracer(String instrumentationScopeName)
      Gets or creates a named tracer instance from the globally registered TracerProvider.

      This is a shortcut method for getTracerProvider().get(instrumentationScopeName)

      Parameters:
      instrumentationScopeName - A name uniquely identifying the instrumentation scope, such as the instrumentation library, package, or fully qualified class name. Must not be null.
      Returns:
      a tracer instance.

    • getTracer

      public static Tracer getTracer(String instrumentationScopeName, String instrumentationScopeVersion)
      Gets or creates a named and versioned tracer instance from the globally registered TracerProvider.

      This is a shortcut method for getTracerProvider().get(instrumentationScopeName, instrumentationScopeVersion)

      Parameters:
      instrumentationScopeName - A name uniquely identifying the instrumentation scope, such as the instrumentation library, package, or fully qualified class name. Must not be null.
      instrumentationScopeVersion - The version of the instrumentation scope (e.g., "1.0.0").
      Returns:
      a tracer instance.

    • tracerBuilder

      public static TracerBuilder tracerBuilder(String instrumentationScopeName)
      Creates a TracerBuilder for a named Tracer instance.

      This is a shortcut method for get().tracerBuilder(instrumentationScopeName)

      Parameters:
      instrumentationScopeName - A name uniquely identifying the instrumentation scope, such as the instrumentation library, package, or fully qualified class name. Must not be null.
      Returns:
      a TracerBuilder instance.
      Since:
      1.4.0

    • getMeterProvider

      public static MeterProvider getMeterProvider()
      Returns the globally registered MeterProvider.
      Since:
      1.10.0

    • getMeter

      public static Meter getMeter(String instrumentationScopeName)
      Gets or creates a named meter instance from the globally registered MeterProvider.

      This is a shortcut method for getMeterProvider().get(instrumentationScopeName)

      Parameters:
      instrumentationScopeName - A name uniquely identifying the instrumentation scope, such as the instrumentation library, package, or fully qualified class name. Must not be null.
      Returns:
      a Meter instance.
      Since:
      1.10.0

    • meterBuilder

      public static MeterBuilder meterBuilder(String instrumentationScopeName)
      Creates a MeterBuilder for a named Meter instance.

      This is a shortcut method for get().meterBuilder(instrumentationScopeName)

      Parameters:
      instrumentationScopeName - A name uniquely identifying the instrumentation scope, such as the instrumentation library, package, or fully qualified class name. Must not be null.
      Returns:
      a MeterBuilder instance.
      Since:
      1.10.0

    • resetForTest

      public static void resetForTest()
      Unsets the global OpenTelemetry. This is only meant to be used from tests which need to reconfigure OpenTelemetry.

    • getPropagators

      public static io.opentelemetry.context.propagation.ContextPropagators getPropagators()
      Returns the globally registered ContextPropagators for remote propagation of a context.