tracing/tracer_factory.h

// Copyright 2026 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//    https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//

#ifndef THIRD_PARTY_CREDENTIO_TRACING_TRACER_FACTORY_H_
#define THIRD_PARTY_CREDENTIO_TRACING_TRACER_FACTORY_H_

#include <memory>

#include "absl/base/nullability.h"
#include "absl/strings/string_view.h"
#include "async/async_context.h"
#include "tracing/tracer.h"

namespace credentio_tracing {

// Abstract factory interface and registry for obtaining Tracer instances.
//
// A factory can be installed at three scopes, consulted in this order:
//
//   1. Per operation, by attaching it to the `credentio::AsyncContext` passed
//   to the
//      operation (`context.SetExtension<TracerFactory>(factory)`). This is the
//      only scope that isolates concurrent operations from one another, and the
//      only one that follows the work across executor hops. Prefer it for any
//      tracer that accumulates per-operation state.
//   2. Per thread, via `SetThreadLocalFactory` (or the `ScopedTracerFactory`
//      guard). Suitable for synchronous callers that cannot thread a context
//      through; it does *not* follow work handed to another thread.
//   3. Process-wide, via `RegisterGlobalFactory`. Suitable for a tracer that
//      is safe to share across all operations, such as one exporting to a
//      metrics backend.
//
// If none is installed the no-op factory is used.
class TracerFactory {
 public:
  virtual ~TracerFactory() = default;

  // Obtains a Tracer associated with the specified component or module name.
  virtual absl_nonnull std::shared_ptr<Tracer> GetTracer(
      absl::string_view tracer_name) const = 0;

  // Registers the global TracerFactory instance. If passed nullptr, resets to
  // the default NoopTracerFactory instance. Thread-safe.
  static void RegisterGlobalFactory(
      absl_nullable std::shared_ptr<TracerFactory> factory);

  // Returns the current global TracerFactory instance. Thread-safe.
  static absl_nonnull std::shared_ptr<TracerFactory> GetGlobalFactory();

  // Installs `factory` for the calling thread only, shadowing the global
  // factory. Passing nullptr clears it. Prefer `ScopedTracerFactory`, which
  // guarantees the factory is cleared on the same thread that installed it.
  static void SetThreadLocalFactory(
      absl_nullable std::shared_ptr<TracerFactory> factory);

  // Returns the factory installed for the calling thread, or nullptr.
  static absl_nullable std::shared_ptr<TracerFactory> GetThreadLocalFactory();

  // Returns the thread-local factory if one is installed, otherwise the global
  // one. Never returns nullptr.
  static absl_nonnull std::shared_ptr<TracerFactory> Get();
};

// Returns the factory that should be used for work performed under `context`:
// the factory carried by the context if it has one, otherwise the thread-local
// factory, otherwise the global one. Never returns nullptr.
absl_nonnull std::shared_ptr<TracerFactory> ResolveTracerFactory(
    const credentio::AsyncContext& context);

// Returns a tracer named `tracer_name` from the factory resolved for
// `context`. This is the form instrumentation should use: passing the context
// keeps spans with the operation they belong to.
absl_nonnull std::shared_ptr<Tracer> GetTracer(
    absl::string_view tracer_name, const credentio::AsyncContext& context);

// As above, for synchronous code with no context to hand. Resolves against the
// thread-local factory, then the global one.
absl_nonnull std::shared_ptr<Tracer> GetTracer(absl::string_view tracer_name);

}  // namespace credentio_tracing

#endif  // THIRD_PARTY_CREDENTIO_TRACING_TRACER_FACTORY_H_