Package io.opentelemetry.api

Class GlobalOpenTelemetry

  • public final class GlobalOpenTelemetry
extends java.lang.Object
    A global singleton for the entrypoint to telemetry functionality for tracing, metrics and baggage.

    If using the OpenTelemetry SDK, you may want to instantiate the OpenTelemetry to provide configuration, for example of Resource or Sampler. See OpenTelemetrySdk and OpenTelemetrySdk.builder for information on how to construct the SDK's OpenTelemetry implementation.

    WARNING: Due to the inherent complications around initialization order involving this class and its single global instance, we strongly recommend *not* using GlobalOpenTelemetry unless you have a use-case that absolutely requires it. Please favor using instances of OpenTelemetry wherever possible.

    If you are using the OpenTelemetry javaagent, it is generally best to only call GlobalOpenTelemetry.get() once, and then pass the resulting reference where you need to use it.

    See Also:
    TracerProvider, ContextPropagators

    • Field Detail

      • GLOBAL_AUTOCONFIGURE_ENABLED_PROPERTY

        private static final java.lang.String GLOBAL_AUTOCONFIGURE_ENABLED_PROPERTY
        See Also:
        Constant Field Values

      • logger

        private static final java.util.logging.Logger logger

      • mutex

        private static final java.lang.Object mutex

      • setGlobalCaller

        @Nullable
private static java.lang.Throwable setGlobalCaller

    • Constructor Detail

      • GlobalOpenTelemetry

        private GlobalOpenTelemetry()

    • Method Detail

      • get

        public static OpenTelemetry get()
        Returns the registered global OpenTelemetry.
        Throws:
        java.lang.IllegalStateException - if a provider has been specified by system property using the interface FQCN but the specified provider cannot be found.

      • 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.

      • getTracer

        public static Tracer getTracer​(java.lang.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​(java.lang.String instrumentationScopeName,
                               java.lang.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​(java.lang.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

      • getMeter

        public static Meter getMeter​(java.lang.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​(java.lang.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.

      • maybeAutoConfigureAndSetGlobal

        @Nullable
private static OpenTelemetry maybeAutoConfigureAndSetGlobal()