tracing/tracer.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_H_
#define THIRD_PARTY_CREDENTIO_TRACING_TRACER_H_

#include <memory>
#include <string>
#include <utility>
#include <vector>

#include "absl/strings/string_view.h"
#include "tracing/span.h"
#include "tracing/thread_context.h"

namespace credentio_tracing {

// Configuration options passed when starting a new span.
struct StartSpanOptions {
  // Optional parent span to establish parent-child relationship.
  Span* parent = nullptr;

  // Initial key-value attribute pairs attached to the span upon creation.
  std::vector<std::pair<std::string, AttributeValue>> attributes;
};

// Abstract interface for creating tracing spans.
class Tracer {
 public:
  virtual ~Tracer() = default;

  // Convenience overload to start a span with default options.
  std::unique_ptr<Span> StartSpan(absl::string_view span_name) const {
    return StartSpan(span_name, {});
  }

  // Creates and starts a new Span with the given name and options.
  std::unique_ptr<Span> StartSpan(absl::string_view span_name,
                                  StartSpanOptions options) const {
    // If no parent span is specified, use the current thread context span
    if (options.parent == nullptr) {
      options.parent = ThreadContext::GetCurrentSpan();
    }
    return StartSpanImpl(span_name, options);
  }

 protected:
  virtual std::unique_ptr<Span> StartSpanImpl(
      absl::string_view span_name, const StartSpanOptions& options) const = 0;
};

}  // namespace credentio_tracing

#endif  // THIRD_PARTY_CREDENTIO_TRACING_TRACER_H_