MEMO

OpenTelemetry C++ Multithreading, Context, and Spans
====================================================

The OpenTelemetry C++ API follows a specific concurrency model that differs from
traditional shared-state multithreading.  Understanding this model is critical
for correct usage and avoiding common pitfalls.


------------------------------------------------------------------------
1. Design Philosophy
------------------------------------------------------------------------

OpenTelemetry C++ avoids shared mutable state.  The API is built on four
principles:

Immutability:
  Core types (Context, SpanContext) cannot be modified after creation.  Any
  "change" produces a new object.  No defensive copying needed, no read/write
  races possible.

Thread-local activation:
  The "current span" concept exists per-thread, not globally.  Each thread
  maintains its own activation stack via thread_local storage.  Creating a Scope
  object activates a span only for the calling thread.

Explicit propagation:
  Context does not automatically flow between threads.  When spawning a worker
  thread or async task, the parent thread must explicitly pass Context or
  extract it for injection into RPC headers.  No implicit inheritance.

Internally synchronized recording:
  Span recording operations (SetAttribute, AddEvent, End) are internally
  mutex-protected by the SDK.  Multiple threads can safely record to the same
  span instance without external synchronization.


------------------------------------------------------------------------
2. Spans
------------------------------------------------------------------------

Spans represent units of work in a distributed trace.  They record timing,
attributes, events, and status.

Conceptual model:

  Spans are write-only sinks for telemetry data.  The API provides methods to
  add information (SetAttribute, AddEvent, SetStatus, End) but intentionally
  omits methods to read that information back.

  A span is not a data structure queried during program execution.  It is an
  append-only log that gets flushed to a backend.

Thread safety guarantees:

  Recording operations are safe from multiple threads:
    thread_1: span->SetAttribute("key1", value1);
    thread_2: span->SetAttribute("key2", value2);
    thread_3: span->End();

  The SDK internally synchronizes these calls (typically with a mutex protecting
  the span's attribute map and event list).  No external locking required.

What is NOT guaranteed:

  Reading span state during execution.  The C++ API has no GetAttribute or
  GetStatus methods.  Even if the underlying implementation exposes such
  methods, using them is incorrect:

    if (span->GetStatus() == StatusCode::kError) { ... }  // WRONG

  No happens-before relationship exists between span operations and application
  logic.  Span recording is asynchronous side-effect.

Common misuse patterns:

  Using spans as IPC mechanism:
    thread_1: span->SetAttribute("ready", true);
    thread_2: while (!span->GetAttribute("ready")) { sleep(); }

    This is fundamentally wrong.  Use proper synchronization primitives
    (condition variables, atomic flags).

  Treating spans as feature flags:
    if (current_span != nullptr) {
      enable_special_mode();
    }

    Observability should not alter program behavior.

  Assuming synchronous export:
    span->End();
    // span data NOT guaranteed to be exported yet

    Spans are typically batched and exported asynchronously.  Use explicit
    Flush() if needed (but rarely required in practice).


------------------------------------------------------------------------
3. Context
------------------------------------------------------------------------

Context is an immutable key-value map that carries cross-cutting concerns
(active span, baggage, correlation data) through the call stack and across
process boundaries.

Implementation characteristics:

  Immutability:
    Context ctx1 = Context::GetCurrent();
    Context ctx2 = ctx1.SetValue(key, value);
    // ctx1 unchanged, ctx2 is new Context with added key

  Structural sharing (copy-on-write):
    Context uses persistent data structure techniques (hash-array mapped tries
    or similar).  Copying a Context is O(1), not O(n).  "Modification" creates
    a new root node pointing to shared subtrees.

  No hidden mutable state:
    No reference counting that could race, no lazy initialization that requires
    locking.  Pure value type.

Thread safety by construction:

  Context can be freely copied between threads:
    std::thread worker([ctx]() {
      // ctx is a copy, completely independent
    });

  No synchronization needed because no mutation exists.  This is different from
  "thread-safe mutable object" (which requires locking).

Usage patterns:

  Propagation within a thread:
    auto ctx = Context::GetCurrent();
    auto span = tracer->StartSpan("operation");
    auto scope = tracer->WithActiveSpan(span);  // modifies thread-local
    // Context::GetCurrent() now returns different context

  Propagation across threads:
    auto ctx = Context::GetCurrent();
    std::thread worker([ctx]() {
      // Must explicitly attach
      auto scope = RuntimeContext::Attach(ctx);
      // Now this thread's GetCurrent() returns ctx
    });

  Propagation across processes (HTTP):
    auto ctx = Context::GetCurrent();
    TextMapPropagator->Inject(carrier, ctx);
    // carrier now contains "traceparent" header
    // Receiving side: Extract(carrier) reconstructs Context

Why immutability matters:

  Without immutability, Context would need locking:
    Context ctx;  // hypothetically mutable
    thread_1: ctx.Set("key1", val1);  // would need mutex
    thread_2: ctx.Get("key2");        // would need mutex

  Or would need thread-local-only usage (no sharing).  Immutability allows both
  free sharing AND zero synchronization cost.


------------------------------------------------------------------------
4. Scope
------------------------------------------------------------------------

Scope is an RAII object that manages the thread-local "current context" stack.
Creating a Scope pushes a Context onto the stack, destroying it pops that
Context off.

How it works:

  auto scope = RuntimeContext::Attach(ctx);
  // Context::GetCurrent() now returns ctx
  // When scope destructs, previous context is restored

  Typical usage with spans:
  {
    auto span = tracer->StartSpan("operation");
    auto scope = tracer->WithActiveSpan(span);
    // span is now "current"
    do_work();  // nested spans will be children
  } // scope destructs here, span no longer current

Thread-local nature:

  Scope uses thread_local storage internally (or equivalent).  Each thread has
  its own independent context stack:

    thread_1:
      auto scope1 = RuntimeContext::Attach(ctx_A);
      // GetCurrent() returns ctx_A in thread_1

    thread_2:
      auto scope2 = RuntimeContext::Attach(ctx_B);
      // GetCurrent() returns ctx_B in thread_2

  Neither thread affects the other.  No global "current span".

Critical pitfall: Scope does not cross thread boundaries:

  WRONG:
    auto span = tracer->StartSpan("parent");
    auto scope = tracer->WithActiveSpan(span);
    std::thread worker([&]() {
      // GetCurrent() does NOT return span here!
      // New thread has empty context stack.
    });

  CORRECT:
    auto span = tracer->StartSpan("parent");
    auto ctx = Context::GetCurrent();  // capture before thread creation
    std::thread worker([ctx, &tracer]() {
      auto scope = RuntimeContext::Attach(ctx);  // explicit attach
      auto child_span = tracer->StartSpan("child");  // now has parent
    });

Why this design:

  Automatic context inheritance across threads would require:
  - Hooking thread creation (not portable)
  - Deciding what to inherit (active span? all baggage? custom keys?)
  - Managing lifetime (when is the inherited context still valid?)

  Explicit propagation is more predictable and works with any threading model
  (std::thread, thread pools, async/await, fibers).


------------------------------------------------------------------------
5. Multithreading Model
------------------------------------------------------------------------

Common concurrency patterns and how OpenTelemetry handles them.

Pattern 1: Worker thread pool

  Main thread creates a span, dispatches work to pool:

    auto span = tracer->StartSpan("request");
    auto ctx = Context::GetCurrent();

    thread_pool.submit([ctx, &tracer, span]() {
      auto scope = RuntimeContext::Attach(ctx);
      auto worker_span = tracer->StartSpan("worker");
      // worker_span is child of span

      process_data();

      worker_span->End();
      span->SetAttribute("processed", true);  // safe, internal lock
    });

    span->End();  // can end before or after worker

  Key points:
  - Context captured before dispatch
  - Worker explicitly attaches context
  - Both threads can record to parent span safely
  - Parent span can be ended from any thread

Pattern 2: Fork-join parallelism

  Parent span, multiple child spans on worker threads:

    auto parent = tracer->StartSpan("parallel_operation");
    auto ctx = Context::GetCurrent();

    std::vector<std::future<void>> futures;
    for (int i = 0; i < N; ++i) {
      futures.push_back(std::async([ctx, i, &tracer]() {
        auto scope = RuntimeContext::Attach(ctx);
        auto child = tracer->StartSpan("parallel_" + std::to_string(i));
        do_work(i);
        child->End();
      }));
    }

    for (auto &f : futures) f.wait();
    parent->End();

Pattern 3: Long-lived background thread

  Background thread maintains its own trace context:

    void background_loop() {
      while (running) {
        auto span = tracer->StartSpan("background_iteration");
        auto scope = tracer->WithActiveSpan(span);

        process_queue();

        span->End();
      }
    }

  Each iteration is independent trace root (no parent).  If processing work
  items that came from other threads, those items should carry Context
  explicitly:

    struct WorkItem {
      Context ctx;  // captured when enqueued
      Data data;
    };

    void background_loop() {
      while (running) {
        WorkItem item = queue.pop();
        auto scope = RuntimeContext::Attach(item.ctx);
        auto span = tracer->StartSpan("process_item");
        // span is child of whatever was current when item was enqueued
        process(item.data);
        span->End();
      }
    }

What does NOT work:

  Assuming implicit propagation:
    void func() {
      auto span = tracer->StartSpan("parent");
      auto scope = tracer->WithActiveSpan(span);
      std::thread worker([]() {
        auto current = trace::GetSpan(Context::GetCurrent());
        // current is INVALID span, not parent!
      });
    }

  Relying on span state for synchronization:
    thread_1: span->SetAttribute("done", true);
    thread_2: poll until span has "done" attribute

    No mechanism exists to query span state, and even if it did, span API is not
    a synchronization primitive.

Core principle:

  Context propagation is a data flow problem, not a control flow problem.  Treat
  Context like any other value passed to functions or threads.


------------------------------------------------------------------------
6. Read and Write Locking Expectations
------------------------------------------------------------------------

Traditional concurrent data structures provide reader-writer locks: multiple
readers OR single writer.  OpenTelemetry uses different strategies.

Context: no locking needed

  Context is immutable (copy-on-write).  No read/write distinction exists
  because no writes exist.  All operations return new Context instances.  Zero
  synchronization cost.

Spans: write-only, internal locking

  Span recording operations (SetAttribute, AddEvent, End) are writes.  No read
  operations exposed by API.  SDK implementation typically uses mutex per span:

    void Span::SetAttribute(string_view key, AttributeValue value) {
      std::lock_guard<std::mutex> lock(mu_);
      attributes_[key] = value;
    }

  Multiple threads writing to same span serialize on this mutex.  This is
  acceptable because:
  - Span writes are infrequent relative to actual work
  - Contention is low (different threads usually record to different spans)
  - Simplicity outweighs lock-free complexity

Providers/Tracers: immutable after initialization

  TracerProvider, MeterProvider, LoggerProvider are initialized once at startup,
  then treated as immutable:

    auto provider = MakeTracerProvider();  // initialization
    trace::Provider::SetTracerProvider(provider);  // publish
    // No further modification allowed

  Tracer and Meter instances obtained from providers are thread-safe for all
  operations (StartSpan, CreateCounter, etc.) because they only read immutable
  configuration.

Instruments (metrics): lock per instrument

  Counter/Histogram/Gauge recording:

    counter->Add(1, labels);

  SDK maintains per-instrument aggregation state protected by mutex.  Similar to
  span recording, contention is acceptable for typical workloads.

When locks are NOT used:

  Thread-local context stack:
    No mutex needed because each thread has independent storage.

  Atomic reference counting:
    shared_ptr uses atomic operations, not mutexes.

  Batching exporters:
    Use lock-free queues or mutexes depending on implementation.  Not exposed to
    API users.

Design principle:

  Prefer immutability and internal synchronization over exposing locking
  requirements to users.  Users should not need to think about mutexes when
  instrumenting code.


------------------------------------------------------------------------
7. Correct Mental Model
------------------------------------------------------------------------

Mental model comparison:

CORRECT mental model:

  OpenTelemetry is structured logging with distributed context.

  Context is like function parameters:
    - Passed explicitly down the call stack
    - Copied when creating threads
    - Immutable values

  Spans are like log statements:
    - Fire and forget
    - Buffered and flushed asynchronously
    - No readback mechanism

  Scope is like RAII resource management:
    - Constructor acquires (activates context)
    - Destructor releases (restores previous context)
    - Strictly lexical scoping

INCORRECT mental model:

  OpenTelemetry is NOT a global variable system:
    - No "current span" accessible from anywhere
    - Thread-local storage requires explicit setup per thread

  OpenTelemetry is NOT a coordination mechanism:
    - Cannot use spans to signal between threads
    - Cannot poll span state to make decisions

  OpenTelemetry is NOT synchronous:
    - Span data may not be exported immediately
    - No guarantee of happens-before between span operations
      and external observable effects

Analogies to other systems:

  Like errno (thread-local state):
    - Each thread has independent errno value
    - Setting errno in one thread doesn't affect others
    - Similar to Context being thread-local

  Like cout (write-only sink):
    - You write to cout, but don't read back what you wrote
    - Output may be buffered, not immediately visible
    - Similar to span recording

  Like std::optional (value semantics):
    - Context behaves like value type, not reference type
    - Copying is cheap and creates independent instance
    - No hidden aliasing

What this means in practice:

  If code relies on "current span" being set:
    void instrumented_function() {
      auto span = trace::GetSpan(Context::GetCurrent());
      if (span->IsValid()) {
        // only instrument if called in traced context
      }
    }

  This is fragile.  Better approach:
    void instrumented_function() {
      auto span = tracer->StartSpan("operation");
      auto scope = tracer->WithActiveSpan(span);
      // always create span, let sampling decide
    }

  If code tries to use spans for control flow:
    span->SetAttribute("phase", "started");
    background_thread.notify();  // WRONG

  Use proper primitives:
    std::atomic<bool> phase_started{false};
    phase_started.store(true, std::memory_order_release);
    background_thread.notify();
    span->SetAttribute("phase", "started");  // informational only


------------------------------------------------------------------------
8. Common Mistakes
------------------------------------------------------------------------

Mistake 1: Not propagating context to new threads

  void handle_request() {
    auto span = tracer->StartSpan("request");
    auto scope = tracer->WithActiveSpan(span);

    std::thread worker([]() {
      // BUG: no context here, new span will be root
      auto span = tracer->StartSpan("work");
    });
  }

  Fix:
    auto ctx = Context::GetCurrent();
    std::thread worker([ctx]() {
      auto scope = RuntimeContext::Attach(ctx);
      auto span = tracer->StartSpan("work");
    });

Mistake 2: Ending span in wrong scope

  void process() {
    auto span = tracer->StartSpan("process");
    auto scope = tracer->WithActiveSpan(span);
    do_work();
    // BUG: span not ended, leaks until scope destructs
  }

  Fix:
    auto span = tracer->StartSpan("process");
    auto scope = tracer->WithActiveSpan(span);
    do_work();
    span->End();  // explicit end before scope destructs

  Or rely on RAII:
    {
      auto span = tracer->StartSpan("process");
      auto scope = tracer->WithActiveSpan(span);
      do_work();
    } // scope destructs, but span->End() must be called explicitly

  Actually, spans typically need explicit End() call.  Check SDK documentation
  for whether automatic ending is supported.

Mistake 3: Capturing span by reference in async lambda

  void async_operation() {
    auto span = tracer->StartSpan("operation");
    thread_pool.submit([&span]() {  // BUG: reference to stack variable
      span->SetAttribute("key", value);  // may dangle
    });
  }

  Fix (copy shared_ptr):
    auto span = tracer->StartSpan("operation");
    thread_pool.submit([span]() {  // copy shared_ptr
      span->SetAttribute("key", value);
    });

Mistake 4: Forgetting to create scope

  void nested_operations() {
    auto parent = tracer->StartSpan("parent");
    // BUG: no scope, so parent not current

    auto child = tracer->StartSpan("child");
    // child is sibling of parent, not child
  }

  Fix:
    auto parent = tracer->StartSpan("parent");
    auto scope = tracer->WithActiveSpan(parent);

    auto child = tracer->StartSpan("child");
    // child correctly parented

Mistake 5: Assuming span data is queryable

  void conditionally_instrument() {
    auto span = trace::GetSpan(Context::GetCurrent());
    if (span->GetAttribute("debug_mode")) {  // NO SUCH METHOD
      enable_verbose_logging();
    }
  }

  Application state should not be stored in spans.  Use separate
  variables:
    bool debug_mode = get_debug_flag();
    if (debug_mode) {
      enable_verbose_logging();
    }
    span->SetAttribute("debug_mode", debug_mode);  // informational

Mistake 6: Race condition on span end

  void parallel_work() {
    auto span = tracer->StartSpan("parallel");

    std::thread t1([span]() { work1(); span->End(); });
    std::thread t2([span]() { work2(); span->End(); });

    // BUG: span->End() called twice
  }

  Fix (coordinator pattern):
    auto span = tracer->StartSpan("parallel");

    std::thread t1([span]() { work1(); });
    std::thread t2([span]() { work2(); });

    t1.join();
    t2.join();
    span->End();  // main thread ends after join

Mistake 7: Not handling exceptions with spans

  void risky_operation() {
    auto span = tracer->StartSpan("risky");
    auto scope = tracer->WithActiveSpan(span);

    might_throw();  // BUG: span not ended on exception

    span->End();
  }

  Fix (RAII or explicit exception handling):
    auto span = tracer->StartSpan("risky");
    auto scope = tracer->WithActiveSpan(span);

    try {
      might_throw();
      span->End();
    } catch (...) {
      span->SetStatus(StatusCode::kError);
      span->End();
      throw;
    }

  Better: use defer/finally pattern or scope guard to ensure End() is always
  called.

Mistake 8: Creating too many spans

  void loop_with_spans() {
    for (int i = 0; i < 1000000; ++i) {
      auto span = tracer->StartSpan("iteration");  // wasteful
      process(i);
      span->End();
    }
  }

  Spans have overhead (allocation, locking, export).  Batch work:
    auto span = tracer->StartSpan("loop");
    for (int i = 0; i < 1000000; ++i) {
      process(i);
    }
    span->SetAttribute("iterations", 1000000);
    span->End();

  Or span only significant iterations:
    for (int i = 0; i < 1000000; ++i) {
      if (is_significant(i)) {
        auto span = tracer->StartSpan("iteration_" + std::to_string(i));
        process(i);
        span->End();
      } else {
        process(i);
      }
    }


------------------------------------------------------------------------
9. Rule of Thumb
------------------------------------------------------------------------

Design principles summary:

  Immutability over locking:
    Context is immutable.  No locks needed.  Compare to alternative design where
    Context is mutable and requires reader-writer lock on every access.

  Thread-local over global:
    Each thread maintains independent activation stack.  No contention.  Compare
    to global "current span" that would require atomic operations or thread-safe
    stack.

  Internal synchronization over exposed locking:
    Span recording methods are internally mutex-protected.  API users never see
    locks.  Compare to API that returns "lock span before modifying"
    requirements.

  Explicit over implicit:
    Context passed explicitly to threads.  No magic.  Compare to automatic
    inheritance that breaks with thread pools or async/await.

  Write-only over read-write:
    Spans are append-only.  No need for consistent snapshots or versioning.
    Compare to queryable span state that would need consistent read protocols.

When to apply these principles to wrapper code:

  The C wrapper (this codebase) must preserve these semantics.  If exposing
  OpenTelemetry to C:

  - Do NOT create global "current span" C APIs
  - Do NOT expose span reading functions (even if C++ SDK has them)
  - Do require explicit context passing in C APIs for thread boundaries
  - Do use opaque handles (IDs) rather than raw pointers for safety

  The sharded map implementation (section 10) follows these principles:
  - Handles are write-heavy (create, destroy), rarely read after creation
  - Per-shard locking avoids global contention
  - Single-threaded mode has zero locking overhead
  - Template-based approach = no runtime configuration overhead

OpenTelemetry avoids concurrency problems by design, not by solving them with
sophisticated locking.  The wrapper should maintain this philosophy.


------------------------------------------------------------------------
10. Sharded Map Implementation
------------------------------------------------------------------------

The C wrapper maintains handle maps (otel_handle<T>) that translate integer IDs
to C++ OpenTelemetry objects (spans, contexts, instruments, views).  A sharded
hash map implementation reduces contention in multi-threaded workloads while
maintaining single-threaded performance.

Access pattern analysis:

  Span and span_context handles:
    - Created and destroyed frequently (per-request in HTTP servers)
    - High concurrent access from multiple worker threads
    - Short-lived (milliseconds to seconds)
    - Configured with the runtime shard count (otel_handle_map_shards)

  Instrument and view handles:
    - Created once during initialization
    - Rarely accessed after creation (cached by application)
    - Long-lived (process lifetime)
    - Configured with 1 shard (degenerates to single map)

Key implementation details:

  Runtime-configured shard count:
    template<typename T, bool shared = true, typename M = std::mutex>
    struct otel_handle { ... };

    The shard count is a constructor argument; the default constructor uses
    OTEL_HANDLE_MAP_SHARDS, and the span and span context maps pass the
    runtime otel_handle_map_shards value (the handle_map_shards YAML key).
    Different handle instances are created with different shard counts.  The
    constructor validates that the count is a power of two and throws
    std::invalid_argument otherwise.

  Storage: std::vector of shards:
    std::vector<struct shard> shards;

    Each shard bundles an std::unordered_map<int64_t, T> with its own
    std::mutex.  The shard storage is heap-allocated by the vector once, at
    construction; size_of() accounts for the vector's shard storage as well as
    each map's buckets and nodes.

  Shard selection: bitwise AND not modulo:
    size_t get_shard_index(int64_t key) const noexcept {
        return static_cast<size_t>(key & (shards.size() - 1));
    }

    On x86-64: single AND instruction vs IDIV (20-80 cycles).
    When the shard count is 1: (key & 0) = 0, always shard 0.
    Requires a power-of-2 shard count (validated by the constructor).

Per-operation locking strategy:

  Single-key operations (find/emplace/erase):
    Per-shard std::mutex under OTELC_USE_THREAD_SHARED_HANDLE.  Lock only the
    target shard.  Other threads access other shards in parallel.  In
    single-threaded mode the mutex member still exists, but it is never taken
    (the lock macros compile to no-ops).

  Cross-shard operations (for_each_locked):
    Iterates over the shards, acquiring each shard's mutex in turn, invoking a
    callback on every entry and clearing the map.  Used during tracer
    destruction to end and delete all remaining handles; taking the mutex
    drains any in-flight operation that already passed its null-check but has
    not yet released the shard lock.

  Duplicate-instrument detection:
    Instrument handles live in a single shard.  create_instrument probes the
    case-folded instrument_index under the shared lock and returns the ID of
    an already-registered instrument on a hit; on a miss it takes the meter's
    create_mutex and re-probes under the shared lock, so only the creation
    winner ever acquires the exclusive map lock and two concurrent creators
    cannot register duplicates.

  ID generation:
    New handle IDs come from an atomic increment of the id counter in both
    threading modes.

Why other approaches were rejected:

  Initial attempt: global mutex serializing all operations.
    Result: worse than unsharded map.  Sharding added overhead without
    parallelism benefit.  Per-shard locking is mandatory.

  Lock-free hash map (libcds, junction, etc):
    More complex, harder to debug.  Per-shard locking is sufficient for observed
    workloads.  Lock-free helps when lock acquisition overhead dominates, but
    handle lookups are infrequent relative to actual span recording operations.

  std::shared_mutex for per-shard locks:
    Overkill for the span and span context maps.  Single-key operations are
    short (hash lookup, insert), so a reader/writer distinction has nothing
    to parallelize within a shard.  The meter maps are the exception: their
    single shard is guarded by otel_shared_mutex so that instrument updates
    can run in parallel (see section 17 and README-meter_performance).

  Compile-time (template parameter) shard count:
    Rejected in favor of a constructor argument.  The vector indirection is
    negligible next to the map lookup and locking, and a runtime count lets
    every handle type share a single template instantiation.

  Fixed shard count:
    Rejected in favor of the handle_map_shards YAML key on top of the
    OTEL_HANDLE_MAP_SHARDS default.  More shards = more memory (each shard
    preallocates buckets), worse cache locality, so the count is tunable per
    deployment; README-sharded_map records the measurements behind the
    default.

Measured behavior:

  Multi-threaded with OTELC_USE_THREAD_SHARED_HANDLE:
    Scaling is sub-linear (2x threads != 2x throughput) due to:
    - Cache line bouncing on atomic id counter
    - Lock acquisition overhead
    Acceptable for production use.

  Single-threaded without OTELC_USE_THREAD_SHARED_HANDLE:
    Performance matches non-sharded std::unordered_map baseline.
    Bitwise AND shard selection + no locking = near-zero sharding cost.
    With a single shard, every lookup resolves to shard 0 and the map behaves
    like a plain std::unordered_map.


------------------------------------------------------------------------
11. Initialization and Deinitialization Architecture
------------------------------------------------------------------------

The library follows a layered initialization model.  otelc_init() creates a
library context that owns the parsed YAML configuration, then per-component
factory functions build the provider/exporter/processor stack from that
configuration.  Deinitialization tears everything down in reverse.

Global entry points:

  otelc_init (src/util.cpp):
    Allocates a library context (struct otelc_ctx) owning the parsed YAML
    configuration document and a duplicated copy of the caller-supplied name.
    Reads the optional top-level handle_map_shards key (the first call whose
    configuration carries a valid key applies it) and records the resolution
    state of the context name against each signal section, readable through
    otelc_ctx_nstate_get().  Multiple contexts may coexist in one process; a
    context must exist before any component is created against it.

  otelc_deinit (src/util.cpp):
    Destroys the logger, meter, and tracer passed in (if provided), then
    closes the YAML configuration document attached to the context, frees the
    context, and clears each pointer.  Only per-context state is touched.

  otelc_close_cfg (src/util.cpp):
    Releases the parsed YAML document attached to a context independently of
    the providers, letting the process drop filesystem access once
    initialization is complete.  The context itself remains valid and is
    still torn down with otelc_deinit().

  otelc_lib_shutdown (src/util.cpp):
    Reinstates the default SDK internal log handler and resets the external
    malloc, free, and thread-ID callbacks to the library defaults.  Called
    once after the final context has been destroyed; optional for a process
    that exits immediately afterwards.

  otelc_ext_init (src/util.cpp):
    Registers external malloc, free, and thread-ID callbacks.  Called from
    otelc_lib_shutdown to reset them.

Per-component lifecycle:

  Each component (tracer, meter, logger) follows an identical pattern: a public
  create function calls an internal factory, which allocates via OTELC_CALLOC,
  zeroes the err and scope_name fields, and wires the ops vtable.

  Component    Public create            Factory          Destroy
  ---------    ---------------          ----------       ----------
  Tracer       otelc_tracer_create      otel_tracer_new  otel_tracer_destroy
  Meter        otelc_meter_create       otel_meter_new   otel_meter_destroy
  Logger       otelc_logger_create      otel_logger_new  otel_logger_destroy

  Structures returned to callers:

    otelc_tracer  (tracer.h)  -- err, scope_name, yaml_prefix, enabled, ops,
                                 ctx, impl
    otelc_meter   (meter.h)   -- err, scope_name, yaml_prefix, enabled, ops,
                                 ctx, impl
    otelc_logger  (logger.h)  -- err, scope_name, yaml_prefix, min_severity,
                                 enabled, ops, ctx, impl

  The ops field in each structure is a vtable pointer that dispatches all
  subsequent operations through indirect function calls.

Handle initialization:

  Tracer initialization creates the span and span context handle maps:
    - otel_span handle (otel_handle<otel_span_handle *>)
    - otel_span_context handle (otel_handle<otel_span_context_handle *>)
    Both are shared by all tracers and use the otel_handle_map_shards count
    (OTEL_HANDLE_MAP_SHARDS by default, overridable through the top-level
    handle_map_shards YAML key).  The maps are reference-counted by the
    tracers and torn down when the last tracer in scope is destroyed.

  Meter initialization creates the per-instance instrument and view handle
  maps:
    - otel_instrument handle (otel_handle<otel_instrument_handle *>)
    - otel_view handle (otel_handle<otel_view_handle *>)
    Both use a single shard (instruments are long-lived, low contention).

  Logger does not use handle maps.

  When OTELC_USE_THREAD_SHARED_HANDLE is defined, handles are shared across
  threads with per-shard mutexes.  Otherwise, handles are thread-local with
  no locking overhead.

  In the dynamic builds the maps are allocated lazily: in the thread-local build
  a thread allocates its maps on its first span start or carrier extraction,
  while the shared-handle build allocates the process-wide maps on the first
  tracer create, serializing concurrent first creates with a function-local
  mutex.  A newly allocated map continues handle numbering from the point where
  the previous map generation stopped, so a leftover span or span context from
  a destroyed generation can never alias a live handle of a newer generation
  with the same index.

  In the thread-local build a span start or carrier extraction may allocate
  the calling thread's maps, while the teardown in otel_tracer_destroy() runs
  only on a thread whose tracer count has dropped to zero.  A thread-exit reaper
  (otel_handle_reaper in src/tracer.cpp), armed just before the per-thread maps
  are allocated, ends the spans still present and frees the maps when the thread
  exits.  A tracer must nevertheless be destroyed on the thread that created it;
  otherwise the creating thread's count never reaches zero and the destroying
  thread's count underflows.  In the shared-handle build the last destroy tears
  the maps down outside the initialization mutex, so create and destroy calls
  that may overlap in time must be serialized externally; concurrent creates
  among themselves and concurrent destroys among themselves remain safe.

Span and span context lifecycle:

  otel_span_new (src/span.cpp):
    Allocates via OTEL_EXT_MALLOC, assigns a monotonically increasing index
    from the otel_span handle, and wires the span ops vtable.  Increments
    alloc_fail_cnt on allocation failure.

  otel_span_destroy / otel_nolock_span_destroy (src/span.cpp):
    Deletes the C++ handle (releasing its shared_ptr) and erases it from the
    handle map without calling End(); a span is ended explicitly through
    end_with_options() or implicitly during tracer destruction.  The nolock
    variant skips lock acquisition for use inside already-locked contexts.

  otelc_span_context_create / otel_span_context_new (src/span.cpp):
    Constructs an otel_trace::SpanContext from trace/span IDs and trace flags,
    wraps it in a DefaultSpan and Context, then emplaces into the
    otel_span_context handle map.

  otel_span_context_destroy / otel_nolock_span_context_destroy:
    Erases the span context from the handle map.

Provider/exporter/processor stack:

  Each component internally creates a provider backed by one or more exporters
  and processors.  The stack is built bottom-up:

    1. otel_*_exporter_create (src/exporter.cpp)
       Creates an exporter from YAML config.  Tracer supports: InMemory,
       OStream, OTLP File, OTLP gRPC, OTLP HTTP, Zipkin.  Meter supports
       the same set except Zipkin; logger replaces InMemory and Zipkin
       with Elasticsearch.

    2. otel_tracer_processor_create / otel_logger_processor_create
       (src/processor.cpp)
       Wraps the exporter in a Batch or Simple processor.  Batch mode
       is configured via max_queue_size, schedule_delay, export_timeout,
       and max_export_batch_size.  Batch pipelines are additionally
       wrapped with otel_counting_span_exporter and
       otel_counting_span_processor (or their log counterparts) for drop
       and export tracking; the Simple processor is not counted.  The
       counters those wrappers keep are read back through
       otelc_pipeline_status_get().

    3. otel_sampler_create (src/sampler.cpp)
       Tracer-only.  Creates AlwaysOn, AlwaysOff, TraceIdRatioBased,
       ParentBased or Composite sampler from YAML config; the composite
       type is compiled in only against an SDK of 1.28 or newer.

    4. otel_*_provider_create (src/provider.cpp)
       Builds a Resource from environment and YAML attributes via
       otel_resource_create (src/resource.cpp), then constructs the provider
       with processors (and sampler for tracer, metric reader for meter).

  Destruction reverses this stack:

    1. otel_*_destroy drops the SDK handle from the per-instance impl,
       preventing new operations.
    2. Force-flushes the per-instance provider with a 5-second timeout.
    3. Releases the impl members; no global SDK provider is touched.
    4. Frees err, scope_name, and yaml_prefix strings.

  Releasing the provider reference in the third step destroys the SDK provider
  object; its destructor calls Shutdown(), which stops and joins the export
  worker threads (batch processors, periodic metric readers) after the bounded
  force-flush of the second step.

  For the tracer, otel_tracer_destroy additionally (when the last tracer in
  scope is destroyed):
    - Destroys all remaining span context handles.
    - Ends all remaining spans and destroys the span handles.
  It also releases the per-instance text map propagator.

Per-instance state:

  Each component keeps its SDK objects (provider, tracer/meter/logger handle,
  and for the tracer the propagator) in a heap-allocated impl structure
  referenced from the public struct.  Operations snapshot the SDK handle from
  the impl and bail out when it is empty; the destroy function drops that
  handle first, before provider teardown.  The drop stops only callers that
  arrive after it and does not synchronize with a snapshot already in flight,
  so destroy must not run concurrently with operations on the same instance,
  as the public destroy operation documents.  No process-wide SDK singletons
  are registered.

Library constructor/destructor (debug builds only):

  otelc_lib_constructor (src/util.cpp):
    __attribute__((constructor)), currently a no-op.

  otelc_lib_destructor (src/util.cpp):
    __attribute__((destructor)), currently a no-op.

Overall initialization flow:

  otelc_init  (create the library context, parse YAML)
    |
    +-- otelc_*_create  (one per component, bound to the context)
    |     |
    |     +-- otel_*_new  (allocate struct and impl, wire vtable)
    |     +-- yaml_resolve_prefix  (locate the signal configuration)
    |     +-- handle map initialization  (tracer shared maps; meter impl maps)
    |
    +-- ops->start  (build the pipeline from the YAML configuration)
          |
          +-- otel_*_exporter_create
          +-- otel_*_processor_create
          +-- otel_sampler_create         (tracer only)
          +-- otel_meter_reader_create    (meter only)
          +-- otel_*_provider_create

Overall deinitialization flow:

  otelc_deinit
    |
    +-- otel_*_destroy  (logger, meter, tracer, via ops vtable)
    |     |
    |     +-- drop the SDK handle from the impl
    |     +-- destroy span context handles (last tracer only)
    |     +-- end remaining spans          (last tracer only)
    |     +-- destroy the span maps        (last tracer, dynamic build)
    |     +-- force-flush provider
    |     +-- release propagator           (tracer only)
    |     +-- release impl and provider    (runs the SDK provider Shutdown)
    |     +-- free err, scope_name, yaml_prefix
    |
    +-- close YAML configuration
    +-- free the context

  otelc_lib_shutdown  (once, after the final context)
    |
    +-- reinstate the default SDK log handler
    +-- reset external malloc/free/thread-ID callbacks


------------------------------------------------------------------------
12. Tracer/Span C++ API/SDK Wrapping Strategy
------------------------------------------------------------------------

The wrapper bridges the C++ OpenTelemetry API to C callers through opaque
handles and vtable-based dispatch.  Each public C struct (otelc_tracer,
otelc_span, otelc_span_context) carries an ops pointer to a function table,
giving C code a virtual-dispatch-like interface without exposing any C++ types.

Tracer per-instance state:

  Each tracer owns an otel_tracer_impl structure (include/tracer.h) holding:

    std::ofstream                  logfile;
    shared_ptr<TracerProvider>     provider;
    shared_ptr<Tracer>             tracer;
    shared_ptr<TextMapPropagator>  propagator;

  Operations snapshot the tracer member and bail out when it is empty.
  During shutdown the member is dropped first, stopping the callers that arrive
  after the drop; calls already in flight must be drained before destroy runs.
  The logfile is declared first so that it is destroyed last, after the provider
  members that may still flush into it.

Tracer startup (otel_tracer_start):

  The function builds the provider stack bottom-up from YAML configuration:

    1. Read scope name from YAML.
    2. Create sampler (AlwaysOn, AlwaysOff, TraceIdRatioBased, ParentBased or
       Composite).
    3. Create exporter-processor pairs.  YAML sequences allow multiple pairs;
       otherwise a single pair is created.
    4. Build TracerProvider, call provider->GetTracer(scope_name,
       OTELC_SCOPE_VERSION, OTELC_SCOPE_SCHEMA_URL).
    5. Set up propagator: either CompositePropagator (HttpTraceContext
       + BaggagePropagator) or HttpTraceContext alone.
    6. Store the provider, tracer, and propagator in the per-instance impl;
       no global SDK provider or propagator is registered.

Span creation (otel_tracer_start_span_with_options):

  Receives C parameters and translates them into C++ API calls:

    otel_trace::StartSpanOptions span_options{};
    span_options.start_system_time  = ...;
    span_options.start_steady_time  = ...;
    span_options.kind               = span_kind_map[kind];
    span_options.parent             = *parent_context;

    /* Without links: */
    auto span = tracer_ptr->StartSpan(operation_name, span_options);

    /* With links: */
    auto span = tracer_ptr->StartSpan(
        operation_name, {}, links_vec, span_options);

  The C enum otelc_span_kind_t maps to otel_trace::SpanKind via a
  constexpr lookup table:

    OTELC_SPAN_KIND_UNSPECIFIED -> SpanKind::kInternal
    OTELC_SPAN_KIND_INTERNAL    -> SpanKind::kInternal
    OTELC_SPAN_KIND_SERVER      -> SpanKind::kServer
    OTELC_SPAN_KIND_CLIENT      -> SpanKind::kClient
    OTELC_SPAN_KIND_PRODUCER    -> SpanKind::kProducer
    OTELC_SPAN_KIND_CONSUMER    -> SpanKind::kConsumer

  Parent resolution follows a priority order:
    - If parent_span is provided, extract context from its handle.
    - If parent_context is provided, extract context from its handle.
    - Otherwise, use RuntimeContext::GetCurrent() (or empty Context when runtime
      context is disabled).

  After StartSpan succeeds, the result is wrapped in an
  otel_span_handle that bundles:
    - otel_nostd::shared_ptr<otel_trace::Span>      (the span)
    - otel_nostd::shared_ptr<otel_context::Context> (propagation ctx)
    - otel_nostd::shared_ptr<otel_trace::Scope>     (RAII activation, only when
      OTELC_USE_RUNTIME_CONTEXT is defined)

  The handle is emplaced into the sharded handle map (shared across
  threads by default, thread-local when OTELC_USE_THREAD_SHARED_HANDLE
  is undefined).  On any allocation failure, the span is ended immediately
  via span->End(EndSpanOptions{}) before cleanup, ensuring no leaked spans
  reach the processor pipeline.

  When span links are provided (via the links/links_len parameters), the
  function builds a vector of (SpanContext, attributes) pairs before allocating
  the span, so that link resolution errors do not require span cleanup.  The
  vector is passed directly to the templated StartSpan(name, attributes, links,
  options) overload, which wraps it in a SpanContextKeyValueIterableView
  internally.  When no links are provided, the original StartSpan(name,
  options) overload is used.

  Unlike AddLink (which requires ABI version 2), links at creation time are
  supported by all ABI versions.

Span operations and their C++ API counterparts:

  C Wrapper Function                 C++ API Call
  ----------------------------------+------------------------------------
  otel_span_get_id                   span->GetContext(), then
                                     span_id().CopyBytesTo(),
                                     trace_id().CopyBytesTo(),
                                     trace_flags().CopyBytesTo()
  otel_span_is_recording             span->IsRecording()
  otel_span_set_status               span->SetStatus(StatusCode, desc)
  otel_span_set_operation_name       span->UpdateName(name)
  otel_span_set_one_attribute        span->SetAttribute(key, val) via
                                     otelc_value_visit visitor
  otel_span_add_event_*              span->AddEvent(name, ts, attr_map)
  otel_span_add_link                 span->AddLink(SpanContext, attr)
                                     (ABI v2+ only)
  otel_span_record_exception          span->AddEvent("exception", ts,
                                     {exception.type, .message,
                                      .stacktrace, ...})
  otel_span_end_with_options         span->SetStatus() then
                                     span->End(EndSpanOptions)
  otel_span_inject_carrier           propagator->Inject(carrier, ctx)

Value dispatch (otelc_value_visit):

  The C wrapper uses a discriminated union (otelc_value with u_type tag) to
  represent polymorphic attribute values.  The otelc_value_visit template
  dispatches on u_type and invokes a callable with the correct C++ type:

    otelc_value_visit(value, [&](auto val) {
        span->SetAttribute(key, val);
    });

  Supported types: bool, int32, int64, uint32, uint64, double, string, and raw
  data (cast to const char *).  Null values map to empty strings.

Baggage propagation:

  Baggage is managed through the span's stored Context object:

    auto baggage = otel_baggage::GetBaggage(*(handle->context));
    baggage = baggage->Set(key, value);
    // ... update context with new baggage via SetBaggage()

  The get/set operations use the Baggage API (GetValue, Set, ToHeader) and
  rebuild the Context immutably on each modification.

Context propagation (inject/extract):

  Injection (otel_span_inject_carrier):
    Populates a std::map<string,string> via
    propagator->Inject(carrier, context), then copies entries to the C-level
    carrier structure.  When composite propagator is not used, baggage is
    injected separately via baggage->ToHeader().

  Extraction (otel_tracer_extract_carrier):
    Populates a std::map from C carrier callbacks, then calls
    propagator->Extract(map_carrier, rt_context).  When composite propagator is
    not used, baggage is extracted separately via BaggagePropagator::Extract().

ABI version awareness:

  AddLink is gated on OPENTELEMETRY_ABI_VERSION_NO >= 2.  Older ABI versions
  return an error message.  start_span_with_options provides an alternative
  that works on all ABI versions by passing links at span creation time.
  Tracer::Enabled() is similarly gated; when unavailable, the wrapper returns
  true unconditionally.

Exception handling discipline:

  The wrapper follows the rule that the OpenTelemetry C++ API does not throw
  exceptions.  try/catch blocks guard only STL operations (std::map::emplace,
  std::vector::push_back, std::string allocations) and external carrier
  callbacks.  OpenTelemetry API calls are never wrapped in try/catch.

Allocation failure handling:

  All heap allocations use std::nothrow or make_shared_nothrow.  Every
  allocation is checked for null.  On failure, the wrapper sets an error message
  on the tracer/span err field and returns OTELC_RET_ERROR (or nullptr for
  pointer-returning functions).  No unguarded new exists in the codebase.

Thread safety model:

  When OTELC_USE_THREAD_SHARED_HANDLE is defined, the sharded handle map
  provides per-shard mutexes.  The OTEL_LOCK_SPAN_HANDLE macro acquires the
  shard lock and resolves the handle in one step:

    OTEL_LOCK_SPAN_HANDLE(_INT, span);
    // 'handle' variable is now available, shard mutex held

  Every span operation acquires the appropriate shard lock before accessing
  the C++ span object.  In single-threaded mode (without
  OTELC_USE_THREAD_SHARED_HANDLE), locking compiles to a no-op.

Tracer shutdown (otel_tracer_destroy):

  Shutdown is ordered to prevent use-after-free:

    1. Drop the SDK Tracer handle from the impl to stop the callers that
       arrive afterwards.
    2. When the last tracer in scope is destroyed: clear span context
       handles, iterate all remaining spans in the handle map, calling
       handle->span->End(end_options) on each, and destroy the span maps
       (dynamic build), saving the id bases for the next map generation.
    3. Force-flush the per-instance provider.
    4. Release the per-instance propagator and provider, delete the impl.
    5. Free err, scope_name, and yaml_prefix strings.

  The spans created by a tracer must already be ended or destroyed when that
  tracer is destroyed, even when other tracers keep the handle maps alive: a
  leftover span remains usable at the SDK level, but its error reporting and
  its inject operation still reach into the freed tracer structure.

  In debug builds the tracer structure carries a liveness marker that destroy
  clears just before the structure is freed.  The span error path probes the
  marker and, for a dead tracer, reports the access loudly and diverts the error
  text into a sacrificial thread-local slot, while the inject operation refuses
  to reach the freed propagator; the probe itself reads freed memory and is
  best-effort by design, like the allocator magic probe.


------------------------------------------------------------------------
13. Meter/Metrics C++ API/SDK Wrapping Strategy
------------------------------------------------------------------------

The meter wrapper follows the same opaque-handle + vtable pattern as the tracer.
The otelc_meter struct carries an ops pointer dispatching through
otelc_meter_ops.  Unlike the tracer (whose sharded maps serve high-churn span
handles), instrument and view handle maps use a single shard because
instruments are long-lived, created once at startup.

Meter per-instance state:

  Each meter owns an otel_meter_impl structure (include/meter.h) holding the
  SDK MeterProvider and Meter, the per-instance instrument and view handle
  maps, the case-folded instrument_index, the create_mutex serializing
  instrument and view creation, and the ostream exporter logfile.  Operations
  snapshot the meter member and bail out when it is empty; shutdown drops it
  first, like the tracer.

Meter startup (otel_meter_start):

  The function builds the provider stack from YAML configuration:

    1. Read scope name from YAML (/signals/metrics/scope_name).
    2. Create one or more exporter-reader pairs.  When the YAML exporters key
       is a sequence, each entry is resolved by name and paired with a matching
       reader (or the last reader if fewer readers than exporters are specified).
       When it is a single value, one exporter-reader pair is created.
    3. Create provider via otel_meter_provider_create(), which attaches each
       reader via AddMetricReader().
    4. Get meter: provider->GetMeter(scope_name, OTELC_SCOPE_VERSION,
       OTELC_SCOPE_SCHEMA_URL).
    5. Store the provider and meter in the per-instance impl; no global SDK
       provider is registered.

  This mirrors the multi-pipeline pattern already used by the tracer
  (processors/exporters) and logger (processors/exporters).

Instrument types:

  Synchronous instruments -- the C wrapper calls Add() or Record() directly on
  the C++ instrument:

    C Enum                   C++ Create Call            Recording
    -----------------------+---------------------------+-----------
    COUNTER_UINT64           CreateUInt64Counter(...)    Add(val)
    COUNTER_DOUBLE           CreateDoubleCounter(...)    Add(val)
    HISTOGRAM_UINT64         CreateUInt64Histogram(...)  Record(val)
    HISTOGRAM_DOUBLE         CreateDoubleHistogram(...)  Record(val)
    UDCOUNTER_INT64          CreateInt64UpDownCounter    Add(val)
    UDCOUNTER_DOUBLE         CreateDoubleUpDownCounter   Add(val)
    GAUGE_INT64  (ABI v2+)   CreateInt64Gauge(...)       Record(val)
    GAUGE_DOUBLE (ABI v2+)   CreateDoubleGauge(...)      Record(val)

  Observable instruments -- the SDK invokes a callback during collection:

    C Enum                        C++ Create Call
    ----------------------------+---------------------------------
    OBSERVABLE_COUNTER_INT64      CreateInt64ObservableCounter
    OBSERVABLE_COUNTER_DOUBLE     CreateDoubleObservableCounter
    OBSERVABLE_GAUGE_INT64        CreateInt64ObservableGauge
    OBSERVABLE_GAUGE_DOUBLE       CreateDoubleObservableGauge
    OBSERVABLE_UDCOUNTER_INT64    CreateInt64ObservableUpDownCounter
    OBSERVABLE_UDCOUNTER_DOUBLE   CreateDoubleObservableUpDownCounter

  Observable instruments use one of two callback adapters:
  otel_meter_observable_int64_cb or otel_meter_observable_double_cb.

Instrument handle structure (otel_instrument_handle):

  Each handle holds all instrument pointer fields simultaneously (only one is
  non-null at a time), selected by the type discriminant:

    unique_ptr<Counter<uint64_t>>      counter_uint64
    unique_ptr<Counter<double>>        counter_double
    unique_ptr<Histogram<uint64_t>>    histogram_uint64
    unique_ptr<Histogram<double>>      histogram_double
    unique_ptr<UpDownCounter<int64_t>> udcounter_int64
    unique_ptr<UpDownCounter<double>>  udcounter_double
    shared_ptr<ObservableInstrument>   observable
    unique_ptr<Gauge<int64_t>>         gauge_int64     (ABI v2+)
    unique_ptr<Gauge<double>>          gauge_double    (ABI v2+)

  The T_CONSTRUCTOR macro generates a separate constructor per instrument type,
  each moving the instrument pointer and recording name/type.
  ObservableInstrument uses shared_ptr because the SDK retains a reference for
  callback invocation.

Observable callback mechanism:

  The OTEL_METER_OBSERVABLE_CB macro bridges C and C++ callback interfaces:

    1. SDK calls otel_meter_observable_int64_cb(observer, state) during
       collection.
    2. The adapter creates a temporary otelc_value on the stack, initialised
       to zero.
    3. Invokes the user's C callback (data->func(data)) which populates
       data->value.
    4. Reads back the value and calls observer->Observe(value) on the C++
       ObserverResult.

  AddCallback / RemoveCallback are dispatched via OTEL_METER_OBSERVABLE_DISPATCH,
  which maps each observable instrument type to the correct callback adapter.
  Synchronous instruments are no-ops in this dispatch.

  The SDK serializes collection per meter: ObservableRegistry::Observe() holds
  the registry mutex across the whole callback loop, so two periodic readers
  never run the callbacks of one meter concurrently.  The wrapper's creation
  and callback registration paths hold the instrument map lock while acquiring
  that same registry mutex, fixing the lock order map lock -> registry mutex;
  a user callback that called back into the meter API would take the locks in
  the opposite order and can deadlock with a concurrent create_instrument.  The
  public descriptor documentation therefore forbids calling meter operations
  from the callback and ties a descriptor to a single meter; collections of
  different meters run concurrently and would race on the shared value slot.

Instrument creation (otel_meter_create_instrument):

  Creates and registers a metric instrument:

    1. Duplicate detection: probe of the case-folded instrument_index (name
       folded to lower case, '/' separator, decimal type) under the shared
       lock.  Returns existing ID if found.
    2. Validate name, description, unit (via InstrumentMetaDataValidator
       when OTELC_USE_INSTRUMENT_VALIDATOR is defined), which only an
       instrument missing from that probe reaches.
    3. Re-probe under the meter's create_mutex, as another thread may have
       created the instrument meanwhile.  Returns existing ID if found.
    4. Dispatch to the appropriate meter_ptr->Create*() call based on type.
    5. Wrap result in otel_instrument_handle and emplace into the
       otel_instrument handle map.
    6. For observable instruments, automatically register the callback via
       otel_nolock_meter_add_instrument_callback.
    7. Register the instrument_index entry last, so a failed creation never
       leaves a stale index entry.
    8. On any failure after emplacement, roll back by erasing from the map and
       deleting the handle.

Value recording:

  Two variants: without attributes (update_instrument) and with attributes
  (update_instrument_kv_n).

  Both:
    - Validate the value type against the instrument type via
      otel_meter_instrument_value_type.
    - Allow int64 -> uint64 coercion for uint64 instruments if the value is
      non-negative.
    - Obtain context: either empty Context{} or RuntimeContext::GetCurrent().
    - Dispatch to Add() (counters/updown) or Record() (histograms/gauges) with
      value, optional attributes map, and context.
    - Observable instruments are no-ops (values come from callbacks).

  C++ API calls invoked per instrument type:

    Instrument Type          C++ API Call
    -----------------------+-------------------------------------
    counter_uint64           counter->Add(uint64_val, [attr], ctx)
    counter_double           counter->Add(double_val, [attr], ctx)
    histogram_uint64         histogram->Record(uint64_val, [attr], ctx)
    histogram_double         histogram->Record(double_val, [attr], ctx)
    udcounter_int64          udcounter->Add(int64_val, [attr], ctx)
    udcounter_double         udcounter->Add(double_val, [attr], ctx)
    gauge_int64 (ABI v2+)    gauge->Record(int64_val, [attr], ctx)
    gauge_double (ABI v2+)   gauge->Record(double_val, [attr], ctx)

View support (otel_meter_add_view):

  Creates and registers metrics views for custom aggregation:

    1. Create InstrumentSelector(type, name, unit) to match instruments.
    2. Create MeterSelector(scope_name, version, schema_url) to match meters.
    3. Create View(name, desc, aggregation_type, config) with optional
       HistogramAggregationConfig for custom bucket boundaries.
    4. Register via provider_sdk->AddView(instrument_selector, meter_selector,
       view).
    5. Track in internal otel_view handle map.
    6. Duplicate views (by name, case-insensitive) return the existing ID
       without re-registration.

  Views must be registered before instruments are created, because the
  OpenTelemetry C++ SDK does not dynamically apply views to existing instruments.

  Supported aggregation types:

    C Enum                               C++ AggregationType
    -----------------------------------+-------------------------
    OTELC_METRIC_AGGREGATION_DROP        kDrop
    OTELC_METRIC_AGGREGATION_HISTOGRAM   kHistogram
    OTELC_METRIC_AGGREGATION_LAST_VALUE  kLastValue
    OTELC_METRIC_AGGREGATION_SUM         kSum
    OTELC_METRIC_AGGREGATION_DEFAULT     kDefault
    OTELC_METRIC_AGGREGATION_BASE2_EXP.. kBase2ExponentialHistogram

  The otelc_meter_aggr_parse() function provides case-insensitive lookup from
  string names ("drop", "histogram", "last_value", "sum", "default",
  "exp_histogram") to the enum values.

Meter enabled check:

  The C++ SDK does not provide a Meter::Enabled() method (unlike
  Tracer::Enabled() in ABI v2).  The wrapper reports the wrapper-level gate
  set via set_enabled() whenever the meter and its SDK handle are valid.

Meter shutdown (otel_meter_destroy):

  Shutdown is ordered to prevent use-after-free:

    1. Drop the SDK Meter handle from the impl to stop the callers that
       arrive afterwards.
    2. Force-flush the per-instance provider.
    3. Clear the view and instrument handle maps (deleting all handles).
    4. Release the impl members and delete the impl.
    5. Free err, scope_name, and yaml_prefix strings.

Key differences from tracer:

  Handle maps use a single shard (instruments are long-lived, low contention)
  while the span maps are sharded (otel_handle_map_shards).

  No per-thread handle storage -- instruments live in the meter instance and
  are shared across threads.

  No "end" operation -- instruments live for the process lifetime.

  Observable instruments invert control: the SDK calls into user code via
  callback adapters, rather than the user calling into the SDK.

  ABI version gates: Gauge<int64_t> and Gauge<double> require
  OPENTELEMETRY_ABI_VERSION_NO >= 2.  All other instrument types are available
  in ABI v1.

Upstream defect in the ostream metric exporter:

  The timestamp helper of the SDK ostream metric exporter calls the plain
  std::gmtime() on every platform but Windows, and the exporter serializes its
  output on a per-instance mutex.  Two meters that each own such an exporter
  therefore format timestamps concurrently through the shared buffer that
  gmtime() returns, which the thread sanitizer reports as a data race in
  exporters/ostream/src/metric_exporter.cc; the versions checked are the pinned
  1.28.0 and the 1.26.0 that is installed.  The consequence is limited to a
  wrong or torn timestamp in the exported text, no wrapper state is involved,
  and the SDK is read-only, so this is recorded for an upstream report rather
  than worked around.  The recordable of the Elasticsearch log exporter, which
  the wrapper also creates, formats its timestamps the same way and without any
  lock at all, so a report should cover both call sites.


------------------------------------------------------------------------
14. Logger/Logs C++ API/SDK Wrapping Strategy
------------------------------------------------------------------------

The logger wrapper follows the same opaque-handle + vtable pattern as the tracer
and meter.  The otelc_logger struct carries an ops pointer dispatching through
otelc_logger_ops.  The logger is the simplest of the three signal components:
it has no handle maps (log records are transient, created and emitted in a
single call) and requires no explicit locking (all vtable operations are marked
"Locking not required").

Logger per-instance state:

  Each logger owns an otel_logger_impl structure (include/logger.h) holding
  the SDK LoggerProvider and Logger and the ostream exporter logfile.
  Operations snapshot the logger member and bail out when it is empty;
  shutdown drops it first, like the tracer and meter.

Logger instance structure:

  Unlike the tracer and meter, the logger struct carries an additional field,
  min_severity:

    struct otelc_logger {
        char                          *err;
        char                          *scope_name;
        char                          *yaml_prefix;
        otelc_log_severity_t           min_severity;
        bool                           enabled;
        const struct otelc_logger_ops *ops;
        const struct otelc_ctx        *ctx;
        void                          *impl;
    };

  The min_severity field defaults to OTELC_LOG_SEVERITY_TRACE (all levels
  allowed) and can be overridden via YAML configuration or changed at runtime
  through set_min_severity().

Severity levels:

  The wrapper defines severity levels matching the OpenTelemetry C++ SDK
  otel_logs::Severity enum, generated from OTELC_LOG_SEVERITY_DEFINES:

    C Enum                       C++ Severity
    ---------------------------+--------------
    OTELC_LOG_SEVERITY_INVALID   kInvalid
    OTELC_LOG_SEVERITY_TRACE     kTrace
    OTELC_LOG_SEVERITY_TRACE2    kTrace2
    OTELC_LOG_SEVERITY_TRACE3    kTrace3
    OTELC_LOG_SEVERITY_TRACE4    kTrace4
    OTELC_LOG_SEVERITY_DEBUG     kDebug
    OTELC_LOG_SEVERITY_DEBUG2    kDebug2
    OTELC_LOG_SEVERITY_DEBUG3    kDebug3
    OTELC_LOG_SEVERITY_DEBUG4    kDebug4
    OTELC_LOG_SEVERITY_INFO      kInfo
    OTELC_LOG_SEVERITY_INFO2     kInfo2
    OTELC_LOG_SEVERITY_INFO3     kInfo3
    OTELC_LOG_SEVERITY_INFO4     kInfo4
    OTELC_LOG_SEVERITY_WARN      kWarn
    OTELC_LOG_SEVERITY_WARN2     kWarn2
    OTELC_LOG_SEVERITY_WARN3     kWarn3
    OTELC_LOG_SEVERITY_WARN4     kWarn4
    OTELC_LOG_SEVERITY_ERROR     kError
    OTELC_LOG_SEVERITY_ERROR2    kError2
    OTELC_LOG_SEVERITY_ERROR3    kError3
    OTELC_LOG_SEVERITY_ERROR4    kError4
    OTELC_LOG_SEVERITY_FATAL     kFatal
    OTELC_LOG_SEVERITY_FATAL2    kFatal2
    OTELC_LOG_SEVERITY_FATAL3    kFatal3
    OTELC_LOG_SEVERITY_FATAL4    kFatal4

  The otelc_logger_severity_parse() function provides case-insensitive lookup
  from string names ("TRACE", "DEBUG2", "INFO", "WARN4", "ERROR", "FATAL3",
  etc.) to the enum values.

  The internal otel_logger_severity() function maps C enum values to C++
  otel_logs::Severity via a static lookup table built from the same
  OTELC_LOG_SEVERITY_DEFINES macro.

Logger startup (otel_logger_start):

  The function builds the provider stack from YAML configuration:

    1. Read scope name from YAML (/signals/logs/scope_name).
    2. Read optional min_severity from YAML (/signals/logs/min_severity) and
       parse via otelc_logger_severity_parse().
    3. Create exporter-processor pairs.  YAML sequences allow multiple pairs;
       otherwise a single pair is created.
    4. Create LoggerProvider with processors via otel_logger_provider_create().
    5. Get logger: provider->GetLogger(scope_name, "", OTELC_SCOPE_VERSION,
       OTELC_SCOPE_SCHEMA_URL).
    6. Set minimum severity on the obtained logger via
       SetMinimumSeverity(uint8_t).
    7. Store the provider and logger in the per-instance impl; no global SDK
       provider is registered.

  The SetMinimumSeverity() method is protected in the C++ Logger base class.
  The wrapper accesses it through a helper struct:

    struct otel_logs_logger : public otel_logs::Logger {
        using otel_logs::Logger::SetMinimumSeverity;
    };

  A static_cast to otel_logs_logger* exposes the method.  The downcast falls
  formally outside the standard, accepted because the subclass adds no members
  or virtual functions and the promoted member is a non-virtual method of the
  base; the setter performs an atomic byte write paired with the atomic read
  in Enabled(), so a runtime severity change needs no wrapper locking.  The cast
  is confined to otel_logger_severity_set(), which carries OTEL_NO_SANITIZE_VPTR
  because the undefined behavior sanitizer reports the downcast on every call;
  keeping it in one small function leaves the check active everywhere else.

Logger enabled check (otel_logger_enabled):

  The logger honors the wrapper-level gate first and, unlike the meter
  (which reports only the gate), then delegates the severity decision to
  the C++ SDK:

    logger_ptr->Enabled(log_severity)

  This allows callers to skip expensive log message construction when the
  logger would discard the record.

Log record creation and emission:

  Record construction is factored into otel_logger_record_create(), which
  creates and populates a log record without setting its body:

    1. Validate the logger pointer.
    2. Convert severity to C++ enum via otel_logger_severity().
    3. Early exit if logger_ptr->Enabled(log_severity) is false.
    4. Copy span_id (8 bytes) and trace_id (16 bytes) to fixed-size stack
       buffers, zero-filled if not provided.
    5. Create log record: logger_ptr->CreateLogRecord().
    6. Populate the record:
       - log_record->SetSeverity(log_severity)
       - log_record->SetSpanId(SpanId{span_id_buf})
       - log_record->SetTraceId(TraceId{trace_id_buf})
       - log_record->SetTraceFlags(TraceFlags{trace_flags})
    7. If ts provided:
       - log_record->SetTimestamp(ts)
    8. If ts_obs provided:
       - log_record->SetObservedTimestamp(ts_obs)
    9. If event_id > 0:
       - log_record->SetEventId(event_id, event_name)
   10. For each attribute:
       - log_record->SetAttribute(key, value) via OTEL_VALUE_ADD

  The formatted variants delegate to otel_logger_log_v(), which validates the
  format string, snapshots the SDK Logger handle from the impl, calls
  otel_logger_record_create(), then:

   11. Format body: vasprintf(&ptr, format, ap).
   12. log_record->SetBody(ptr).
   13. logger_ptr->EmitLogRecord(std::move(log_record)).
   14. free(ptr).
   15. Return the character count; an emitted empty body returns 0, which
       is indistinguishable from a disabled severity or a cleared gate.

  The body variants (log_body, log_body_span) skip otel_logger_log_v() and
  vasprintf entirely: they call otel_logger_record_create() and set a typed
  body from an otelc_value (string, data, integer, double, or boolean) via
  SetBody() before emitting.

  C++ API calls used per log record:

    C++ API Call                         Purpose
    -----------------------------------+----------------------------
    logger->CreateLogRecord()            allocate new record
    log_record->SetSeverity()            severity level
    log_record->SetSpanId()              trace correlation
    log_record->SetTraceId()             trace correlation
    log_record->SetTraceFlags()          sampling flags
    log_record->SetTimestamp()           event time
    log_record->SetObservedTimestamp()   receipt time
    log_record->SetEventId()             structured event marker
    log_record->SetAttribute()           key-value metadata
    log_record->SetBody()                formatted message
    logger->EmitLogRecord()              send to pipeline

Log entry points:

  Four public variants exist; the formatted pair maps to the internal
  otel_logger_log_v(), the body pair emits an otelc_value directly:

  log() -- takes explicit span_id, trace_id, and trace_flags as raw byte
  buffers.  The variadic arguments are forwarded via va_list.

  log_span() -- takes an otelc_span pointer instead.  Extracts span_id,
  trace_id, and trace_flags by calling the span's own get_id() operation
  (span->ops->get_id()), then delegates to otel_logger_log_v().  Handles NULL
  span gracefully by using zeroed buffers.

  log_body() / log_body_span() -- same trace-correlation choices as log() and
  log_span(), but the body is a typed otelc_value instead of a printf-style
  format string.

Runtime severity change (otel_logger_set_min_severity):

  Changes the minimum severity threshold at runtime:

    1. Convert severity to C++ enum.
    2. Cast logger_ptr to otel_logs_logger* to access
       SetMinimumSeverity(uint8_t).
    3. Update logger->min_severity field.

  After this call, the C++ SDK's Enabled() check will reflect the new threshold.

Logger shutdown (otel_logger_destroy):

  Shutdown is ordered to prevent use-after-free:

    1. Drop the SDK Logger handle from the impl to stop the callers that
       arrive afterwards.
    2. Force-flush the per-instance provider.
    3. Release the impl members and delete the impl.
    4. Free err, scope_name, and yaml_prefix strings.

Key differences from tracer and meter:

  No handle maps -- log records are transient, created and emitted in a single
  function call.  There is no equivalent of a span handle or instrument handle
  that persists across calls.

  No locking required -- all operations either snapshot the SDK logger handle
  from the impl or operate on function-local data (the log record).  The
  vtable comments confirm "Locking not required" for every operation.

  Severity filtering -- the logger has a min_severity threshold that is both
  configurable at startup via YAML and changeable at runtime via
  set_min_severity().  The C++ SDK's Enabled() method enforces the threshold,
  allowing the wrapper to skip record creation for filtered levels.

  Body formatting -- log() and log_span() produce the body as a printf-style
  string via vasprintf() and set it with SetBody(); log_body() and
  log_body_span() set a typed body directly from an otelc_value (string,
  data, integer, double, or boolean).

  Trace correlation -- log records can be associated with distributed traces
  either by providing raw span/trace IDs (log()) or by passing an otelc_span
  pointer (log_span()) from which the IDs are extracted automatically.

  Event identification -- log records support SetEventId(int64_t, str) for
  structured event tagging, a feature not present in span or metric APIs.


------------------------------------------------------------------------
15. Memory Allocation and Deallocation
------------------------------------------------------------------------

The project implements a layered memory management system designed for
integration into applications (such as HAProxy) that may require custom
allocators.

Allocation infrastructure:

  Debug tracking layer (dbg_malloc.h/cpp) -- wraps every allocation with source
  location (function name, line number) tracking, enabled via the DEBUG or
  DEBUG_OTEL compile flag.  This allows leak detection at runtime without
  external tools.  Section 19 describes the tracker internals in detail.

  External allocator interface (otelc_ext_init) -- allows callers to register
  custom malloc/free function pointers.  The OTEL_EXT_MALLOC and
  OTEL_EXT_FREE_CLEAR macros dispatch through these pointers.  Passing NULL
  resets to the default (debug-tracked or libc).

  Safe free macros -- OTELC_SFREE (NULL-safe free), OTELC_SFREE_CLEAR (NULL-safe
  free that also sets the pointer to NULL), and OTEL_EXT_FREE_CLEAR (external
  allocator variant that sets to nullptr).

  Duplication macros -- OTELC_STRDUP and OTELC_STRNDUP resolve to the tracked
  otelc_dbg_strdup/otelc_dbg_strndup in a debug build and to the exported
  otelc_strdup/otelc_strndup wrappers otherwise, so both builds return NULL
  for a NULL argument instead of leaving that to the C library.

  C++ nothrow wrappers (std.h) -- make_unique_nothrow and make_shared_nothrow
  handle both new(std::nothrow) failure and shared_ptr control block allocation
  failure.  In make_shared_nothrow, the catch clause must not delete the raw
  pointer: when the shared_ptr constructor throws std::bad_alloc it has
  already taken ownership and deletes the pointer before propagating, so
  deleting it again would be a double free.

  Deferred cleanup (OTEL_DEFER) -- provides RAII-style scope cleanup through a
  C++ helper object whose destructor runs the deferred expression at scope
  exit.

Allocation patterns by signal:

  Tracer -- the otelc_tracer struct is allocated with OTELC_CALLOC in
  otel_tracer_new() and freed with OTELC_SFREE_CLEAR in otel_tracer_destroy().
  The scope_name and yaml_prefix strings are allocated with OTELC_STRDUP or
  OTELC_MALLOC and freed with OTELC_SFREE, while the err member is produced by
  otelc_sprintf() (see below).  Span and span context C handles are allocated
  with OTEL_EXT_MALLOC and freed with OTEL_EXT_FREE_CLEAR.  C++ handle objects
  (otel_span_handle, otel_span_context_handle) are allocated with
  new(std::nothrow) and deleted during the handle map teardown in destroy
  (clear_locked() or the for_each_locked() span walk), or explicitly in error
  paths before map insertion.

  Meter -- same struct pattern as tracer.  Instrument and view handles are
  allocated with new(std::nothrow) and tracked in single-shard handle maps.
  Cleanup via clear_locked() in otel_meter_destroy().

  Logger -- same struct pattern as tracer.  No handle maps; log records are
  transient, created by the C++ SDK's CreateLogRecord() and emitted in the same
  call.  The log body is formatted with vasprintf() which allocates via malloc;
  the result is handed to SetBody(), which converts it into a value the record
  owns, and is freed with free() once EmitLogRecord() has returned.

Text map memory management:

  otelc_text_map_new() allocates the struct (if dynamic) and three parallel
  arrays (flags, key, value) with OTELC_CALLOC.  otelc_text_map_add() grows
  these arrays with OTELC_REALLOC when capacity is exceeded.  Key and value
  strings are optionally duplicated (OTELC_TEXT_MAP_DUP_KEY/VALUE) and freed
  according to ownership flags (OTELC_TEXT_MAP_FREE_KEY/VALUE).

  The standard flag OTELC_TEXT_MAP_AUTO (used by every caller in the codebase)
  sets DUP|FREE for both key and value, ensuring ownership is always transferred.

  The sequential realloc pattern (flags, then key, then value) does not leak
  on partial failure.  When a later realloc fails, earlier arrays may be
  over-allocated relative to text_map->size (which is only updated after all
  three succeed), but all memory remains reachable through the struct and is
  freed during text_map cleanup.

Error path cleanup in span creation:

  otel_tracer_start_span_with_options() has several failure points after
  otel_span_new() returns.  Each calls span->End() to prevent SDK-level resource
  leaks (the SDK may have already started export timers), followed by
  otel_nolock_span_destroy() to clean up the C handle.  A copy of the span
  shared_ptr (span_end) is kept before moving it into the handle, ensuring End()
  can still be called if handle construction fails.

Orphaned span cleanup:

  otel_tracer_destroy() iterates all remaining span handles via
  for_each_locked() and calls span->End() before tearing down the provider,
  ensuring orphaned spans are still exported.  Span context handles are cleared
  first since they do not require End().

Global teardown order:

  otelc_deinit() destroys the logger, meter, and tracer passed in (reverse of
  typical startup order), then closes the YAML document attached to the
  context and frees the context.  Process-wide hooks stay untouched; a final
  otelc_lib_shutdown() call resets the external callback pointers via
  otelc_ext_init(NULL, NULL, NULL) and reinstates the default SDK log handler
  once every context is gone.

  Each signal's destroy function drops the SDK handle from its impl before
  provider teardown, preventing concurrent callers from accessing a
  half-destroyed signal.

otelc_sprintf() ownership transfer:

  otelc_sprintf() (used by the OTEL_*_ERROR macros to set the err member) frees
  the old *ret string before assigning the new one from vasprintf().  If
  vasprintf() fails, *ret is freed and left NULL.  The replacement of *ret is
  serialized by an internal mutex, so concurrent error paths that signal on
  the same target (for example meter->err) cannot double-free the previously
  stored string.


------------------------------------------------------------------------
16. YAML Configuration Parsing
------------------------------------------------------------------------

The YAML module provides a dual-backend configuration parser that supports two
YAML libraries selected at compile time via the HAVE_LIBFYAML_H preprocessor
flag:

  libfyaml -- a C library accessed through the fy_document_* API.  Values are
  resolved with fy_node_by_path() and copied out of the scalar nodes.

  rapidyaml (default) -- a C++ library accessed through ryml::Tree with a custom
  ryml_get_node_by_path() traversal function that handles both map keys and
  numeric sequence indices.

Every function has parallel implementations for both backends with matching
semantics; the one intended difference is the duplicate-key rejection that
only the rapidyaml build performs at load time.  The OTEL_YAML_DOC typedef
abstracts the document type.

Path traversal (rapidyaml backend):

  ryml_get_node_by_path() splits a slash-separated path and walks the tree node
  by node.  For map nodes it calls has_child(part); for sequence nodes it parses
  the numeric index character by character and validates the bounds against
  num_children().  A numeric segment that would overflow size_t is rejected
  before the bounds check, so a wrapped index can never select a wrong node.
  The edge cases of empty path (returns root), leading slash, and empty path
  segments are handled explicitly.

Error handling:

  ryml_throw_error() is registered as the rapidyaml error callback.  It throws
  std::runtime_error, which is caught by the OTEL_CATCH_SIGNAL_RETURN macro in
  the YAML module's try blocks.  The routing was verified against rapidyaml
  0.10: the temporary parser used by the freestanding parse_in_arena() reports
  errors through the tree's callbacks, so the throwing handler installed on
  the tree contains malformed input and a parse error cannot abort the process.

  yaml_open() wraps tree allocation and parsing in a single try block.  On
  success the unique_ptr is released to transfer ownership to the caller.

  In the rapidyaml build, yaml_open() additionally runs the duplicate-key scan
  ryml_find_duplicate_keys(), which rejects a document whose mappings repeat
  a key, reporting the full node path; the libfyaml build performs no such
  check.

  yaml_read() uses OTEL_DEFER(yaml_close(&fyd)) for automatic document cleanup
  regardless of the exit path.

Upstream defect in the libfyaml scanner:

  The fuzzing campaign of the libfyaml backend found a five-byte document, the
  '%' directive marker followed by the bytes 01 a9 00 00, on which libfyaml 0.9
  never returns: it spins inside fy_scan_directive() below the document build
  call.  A plain program that only builds a document from that file reproduces
  the hang without any wrapper code, so otelc_init() of a libfyaml build hangs
  on such a configuration file and no wrapper-side timeout can break out of the
  library call.  The file has to be supplied by the operator, which bounds the
  exposure, and the default rapidyaml backend rejects the same input normally.
  Recorded for an upstream report; the SDK and the YAML libraries stay
  untouched.

Value extraction:

  yaml_find() retrieves a scalar value by path.  Both backends resolve the node
  first -- fyaml_copy_scalar() with fy_node_by_path(), the rapidyaml build with
  the tree walker -- and copy the value with the length-safe otelc_strlcpy(),
  so no lookup interprets the path as a format string.  The '%' rejections in
  yaml_resolve_prefix() and yaml_get_node() remain as a defense in depth so
  that conversion specifiers stay out of the resolved paths altogether.

  yaml_get_node_v() is the variadic core that parses typed properties (STR,
  BOOL, INT64, DOUBLE, MAP) from a named YAML node.  Integer parsing uses
  strtoll with proper errno/endptr validation.  Double parsing uses strtod with
  the same.  The %s substitution in path templates is format-safe because the
  templates are compile-time strings with a single %s placeholder.

  The PRAGMA_DIAG_IGNORE/PRAGMA_DIAG_RESTORE pairs around format-nonliteral
  warnings are correctly scoped to the snprintf calls that use non-literal
  format strings.

Sequence operations:

  yaml_get_sequence() extracts key-value pairs from a sequence of mappings into
  an otelc_text_map.  The text map is allocated on first use.  Both backends
  iterate children and populate the map with OTELC_TEXT_MAP_AUTO (DUP|FREE)
  flags.

  yaml_get_sequence_len() returns the child count.  yaml_get_sequence_value()
  retrieves a scalar at a given index with bounds checking.  yaml_is_sequence()
  tests whether a path points to a sequence node.

  yaml_find_sequence() resolves a sequence name via yaml_find() then calls
  yaml_get_sequence() on the resolved path.  This function is currently unused
  but tested and retained for potential future use.

Library lifecycle:

  yaml_open() opens and parses a YAML file.  yaml_close() releases the document
  and sets the pointer to nullptr.  Each library context created by
  otelc_init() owns its document (otelc_ctx.fyd); otelc_deinit() closes it
  when the context is destroyed, and otelc_close_cfg() may close it earlier,
  once initialization is complete.

  Multiple contexts may coexist within one process, each with its own
  configuration document and name.  Reinitialization after deinit is
  supported.


------------------------------------------------------------------------
17. Locking Mechanism
------------------------------------------------------------------------

The project supports two threading models selected at compile time via
OTELC_USE_THREAD_SHARED_HANDLE (default: enabled).

Threading models:

  Shared-handle model (default) -- span and span_context handles live in global
  structures.  OTEL_LOCK_TRACER(type, idx) acquires a per-shard std::mutex via
  lock_guard.  The shard is selected by idx & (num_shards - 1), giving one
  independent lock per shard for spans.  THREAD_LOCAL expands to nothing;
  OTEL_HANDLE_SHARED is true.

  Thread-local model -- handles are thread_local.  OTEL_LOCK_TRACER(...)
  compiles to while(0) (no-op).  No contention possible since each thread has
  its own map.  THREAD_LOCAL expands to the thread_local keyword;
  OTEL_HANDLE_SHARED is false.

  Meter handles (otel_instrument, otel_view) live in the meter instance, are
  shared across threads (not thread-local), and sit in a single shard whose
  mutex is an otel_shared_mutex, a wrapper around std::shared_mutex that adds
  writer preference.  Lookups and instrument updates take it shared via
  OTEL_LOCK_METER_SHARED(type) and run in parallel; creation is serialized on
  the meter's create_mutex and takes the map lock exclusively only for the
  final insert, and teardown locks exclusively via OTEL_LOCK_METER(type).
  Instruments are long-lived and created once at startup, so the exclusive
  path is cold.

Handle structure (otel_handle<T, shared, M>):

  Each handle contains a vector of shards, where each shard holds an
  unordered_map and a mutex of the type selected by the M template parameter
  (std::mutex by default, otel_shared_mutex for the meter maps).  The
  constructor validates that num_shards is a power of two (required for the
  bitmask in get_shard_index).

  Atomic members (id, peak_size, alloc_fail_cnt, erase_cnt, destroy_cnt) use
  std::atomic and require no lock.  The id counter uses operator++ which is
  sequentially consistent by default, making ID generation race-free even in
  the shared-handle model.

  Peak size tracking uses a compare_exchange_weak retry loop to atomically
  update the high-water mark without a lock.

Lock acquisition patterns:

  Single-lock operations -- functions like otel_span_get_id,
  otel_span_set_status, otel_span_set_attribute_*, and otel_span_add_event_*
  each acquire exactly one shard lock via OTEL_LOCK_SPAN_HANDLE, do their work,
  and return.  The lock_guard scope covers the entire operation.

  Multi-lock operations -- otel_span_add_link and
  otel_tracer_start_span_with_options access multiple handles
  (link target + span, or parent + new span).  In both cases, the first lock is
  released before the second is acquired: the lock_guard goes out of scope at
  the end of an if/else block or loop iteration, and the next lock is acquired
  in a subsequent block.  At no point are two shard locks held simultaneously.
  No deadlock is possible.

  Manual locking -- otel_span_get_baggage_var uses OTEL_LOCK_TRACER directly
  instead of OTEL_LOCK_SPAN_HANDLE because it needs custom error handling
  (destroying the text map before returning on failure).

Guard variable naming:

  The guard_##a naming convention means OTEL_LOCK_TRACER(span, idx1) creates
  guard_span.  A second OTEL_LOCK_TRACER(span, idx2) in the same scope would
  cause a redefinition error, providing a compile-time safety net against
  accidental double-locking of the same handle type.  Functions that need
  multiple locks use separate scoped blocks.

Meter locking:

  Meter operations lock shard[0].mutex, an otel_shared_mutex (a wrapper around
  std::shared_mutex that adds writer preference): lookups, updates of the
  instruments and observable callback registration take it shared through
  OTEL_LOCK_METER_SHARED(instrument), while map mutation and teardown take it
  exclusively via OTEL_LOCK_METER(instrument) or OTEL_LOCK_METER(view).  Since
  instruments and views are separate handle structures, guard_instrument and
  guard_view are different mutex instances.
  otel_meter_create_instrument probes the instrument_index under the shared
  lock, serializes on the meter's create_mutex, re-probes under the shared
  lock and only then, as the single creation winner, performs the SDK creation
  and takes the exclusive lock for the map and index insert and the optional
  callback registration.
  otel_nolock_meter_add_instrument_callback is called while the instrument lock
  is already held (hence "nolock" in the name).

Teardown locking:

  for_each_locked() iterates all shards sequentially, locking each shard's mutex
  before clearing.  The if constexpr (shared) branch only acquires the lock when
  OTEL_HANDLE_SHARED is true.  In the thread-local model, no locking is needed
  during teardown.

  Each signal's destroy function resets the SDK handle held in the impl
  struct before tearing down the provider: otel_tracer_destroy() assigns
  impl->tracer = {} before flushing and clearing impl->provider, and the
  meter and logger destroys follow the same pattern.  These assignments
  are plain shared_ptr resets, not atomics, so they do not by themselves
  synchronise with concurrent readers.  The library therefore relies on
  the caller to drain in-flight tracer/meter/logger operations before
  invoking destroy, after which the per-shard mutexes inside the handle
  maps cover the implicit teardown of any spans, instruments, or views
  that were still registered.


------------------------------------------------------------------------
18. Runtime Enable/Disable Gate for Signals
------------------------------------------------------------------------

Each of the three signal-carrying structures -- otelc_tracer, otelc_meter and
otelc_logger -- carries a bool member named "enabled" that gates the wrapper
between the caller and the underlying OpenTelemetry C++ SDK.  The member is
initialised to true when the structure is allocated, so the default behaviour
matches the wrapper as it existed before the gate was introduced.  When the
gate is cleared, the wrapper short-circuits requests at its public boundary
and the SDK is never reached.

The gate is toggled through a vtable entry, set_enabled, present on each of the
three operations tables.  It accepts a bool and returns OTELC_RET_OK on success
or OTELC_RET_ERROR when the pointer to the signal structure is NULL.  When the
wrapper-level gate is cleared, that state is also reflected in the existing
enabled() vtable entry, so a caller that performs the usual "enabled?" probe
before constructing telemetry data sees one consistent answer regardless of
whether the gate or the underlying SDK is the cause of the rejection.

Toggle mechanism:

  Usage from C is identical to any other vtable call:

      tracer->ops->set_enabled(tracer, false);    /* stop new spans */
      ...
      tracer->ops->set_enabled(tracer, true);     /* resume         */

  The same pattern applies to meter->ops->set_enabled() and to
  logger->ops->set_enabled().  Exposing the gate as a vtable entry rather than a
  direct field assignment keeps it next to the other operations, preserves the
  OTELC_NONNULL contract, and leaves room to evolve later (for example, by
  emitting a log message on transition, or by gating against a configuration
  source other than a single bool) without changing the public ABI.

Gating choice -- behaviour for already-open spans:

  Clearing the gate while a span is in flight, a log record is being prepared,
  or a metric instrument is being created admits three distinct policies.  The
  wrapper implements the first; the other two are documented here so that the
  alternative paths are not lost if the topic is revisited later.

  Gate creation only (implemented):

    Only the entry points that create new telemetry primitives consult the gate:

      * tracer: start_span, start_span_with_options, extract_text_map,
                extract_http_headers

      * meter:  create_instrument, add_view

      * logger: log, log_span, log_body, log_body_span

    When the gate is cleared, these entry points return their idle value
    without handing anything new to the underlying SDK: nullptr for span
    creation and context extraction, OTELC_RET_ERROR for instrument and view
    creation, and 0 (the "severity not enabled" code) for log emission.  The
    log_span and log_body_span wrappers still read the trace and the span
    identifiers from the given span before the gate check, but emit nothing
    once the gate turns out to be cleared.  Operations performed on the
    spans that were already started, on the instruments that were already
    registered, and on the log records that were already submitted continue to
    run unchanged: they reach the SDK exactly as before, they are exported by
    the configured processors, and they end on their natural lifecycle.

    This is the simplest and most predictable of the three policies.  It treats
    the gate as a back-pressure knob over new work rather than as a kill switch
    for live work, and it never produces a half-formed span or a truncated log
    record.  The trade-off is that telemetry continues to flow from in-flight
    objects for as long as those objects live; callers who need an immediate
    cessation must combine the gate with force_flush followed by shutdown or
    destroy.

  Gate every operation (not implemented):

    Under this alternative the span, log-record and instrument operations would
    also consult the gate.  A span->set_attribute() call on a span whose parent
    tracer is disabled would silently no-op, as would record_value() on a metric
    instrument under a disabled meter.  Every span carries a back-pointer to its
    tracer through the otelc_span field "tracer", and the metric and log
    operations route through their parent structures as well, so the runtime
    lookup is cheap.

    This alternative produces more uniform observed behaviour after a disable:
    no further mutation reaches the SDK from any wrapper entry point.  Its
    drawback is that End() on a span must still be allowed through (otherwise
    the SDK leaks a span record), so the SDK sees a span whose attributes and
    events were truncated at an arbitrary point in time.  Downstream consumers
    that correlate by trace_id may then receive a span that is structurally
    valid but semantically misleading.

  Hard cut on disable (not implemented):

    The most aggressive policy treats clearing the gate as an implicit cleanup
    event.  set_enabled(tracer, false) would walk the span handle map, would
    call End() on every live span, and would clear the map.  set_enabled(meter,
    false) would force_flush the periodic readers and would drop the instrument
    and view maps.  set_enabled(logger, false) would force_flush all pending log
    records.  The SDK then never sees half-formed data: every live object either
    completes cleanly or is gone before the call returns.

    The drawback is invasiveness.  A caller that toggled the gate twice in quick
    succession would lose all telemetry context across the toggle, which is
    rarely what monitoring code wants.  The implementation would also have to
    acquire the span shard locks in bulk and serialise against in-flight span
    operations, which is at odds with the wrapper's normal "fine-grained
    locking, no global mutex" stance.

Interaction with shutdown and destroy:

  Clearing the gate is independent of force_flush, shutdown and destroy.  Those
  three operations remain available while the gate is cleared, and they behave
  exactly as they do when the gate is set.  Callers who want to drain the
  in-flight telemetry after disabling new work should follow set_enabled with
  force_flush; callers who want the underlying SDK provider to release its
  resources should follow with shutdown or destroy as appropriate for the
  affected signal.


------------------------------------------------------------------------
19. Debug Memory Tracker
------------------------------------------------------------------------

Debug builds route the entire OTELC_MALLOC macro family through the otelc_dbg_*
wrappers in src/dbg_malloc.cpp, which prepend a metadata header to each block
and record each allocation in a caller-supplied table.  The tracker detects
leaks, double frees and stray frees at runtime without external tools, and it
degrades gracefully whenever it cannot track a block.  The OTELC_DBG_MEM macro
gates the whole facility; it is derived from DEBUG or DEBUG_OTEL in the public
debug.h header, and the debug library's pkg-config file supplies -DOTELC_DBG_MEM
to consumers.

Block layout:

  Every allocation reserves room for a header (struct otelc_dbg_mem_metadata)
  in front of the payload: DBG_MEM_SIZE() adds the header size to the request,
  DBG_MEM_RETURN() hands the caller the payload address behind the header, and
  DBG_MEM_DATA() maps a payload pointer back to the header.  The header stores
  a pointer to the allocation record and the magic value (DBG_MEM_MAGIC) that
  marks blocks coming from these wrappers.

Tracker state and lifecycle:

  otelc_dbg_mem_init() receives a caller-owned otelc_dbg_mem state structure
  together with an array of allocation records, initializes a recursive pthread
  mutex and then publishes the tracker through a file-scope pointer.  The test
  harness in test/test.c initializes the tracker early in main() and prints
  the final report with OTELC_MEMINFO() at the end of the run; any chunk still
  listed there is a leak.  otelc_dbg_mem_info() prints the operation counters,
  every live chunk with the location that allocated it, and the process-wide
  mallinfo()/mallinfo2() statistics when available.

  otelc_dbg_mem_disable() clears the tracker pointer under the mutex, so an
  operation that races on another thread either completes first or detects the
  disabling after it acquires the mutex and backs out.  The mutex itself is
  never destroyed on purpose, since a thread may still be blocked on it, and
  destroying a mutex in that state is undefined behavior.  The caller-owned
  state structure must therefore outlive all tracked activity.

Record management:

  Records live in the fixed-size caller-supplied array.  A new allocation first
  takes a never-used slot (high-water cursor); once every slot has been touched,
  a scan starting at the reuse cursor claims the first record no longer in use.
  When no slot is free the block stays allocated but untracked, and an overflow
  diagnostic is emitted after the mutex has been released.

Untracked and foreign blocks:

  A block allocated before otelc_dbg_mem_init(), after the tracker was disabled,
  or while the record table was full carries self-referencing metadata: the
  header is valid but points at itself instead of a record.  otelc_dbg_free()
  and otelc_dbg_realloc() recognize this state and release or reallocate the
  real base directly, re-initializing the header after each realloc so the stale
  self-pointer is never followed.

  A pointer whose header carries no valid magic value was not produced by these
  wrappers at all; it is freed or reallocated transparently through the plain
  C library calls.  The magic probe reads below the payload, which is formally
  undefined for these foreign blocks; in practice the read lands inside the
  allocator's chunk header, and the accepted risk is documented at the probe
  in src/dbg_malloc.cpp.  The probe is confined to otelc_dbg_is_wrapper_block(),
  which carries the DBG_MEM_NO_ASAN attribute because the address sanitizer
  reports that read as a heap underflow and offers no runtime suppression for
  a memory error.

Double-free defense:

  A release is rejected when the record shows that the block is not currently
  allocated or does not match the pointer, which indicates a double or stray
  free.  The memory is then deliberately left untouched after the diagnostic,
  accepting a leak rather than risking heap corruption; records whose pointer
  matches the rejected block are listed as possible previous uses.

Error string tracking:

  otelc_sprintf() obtains its result from vasprintf(), which allocates with
  plain malloc().  In a debug build OTELC_DBG_MEM_TRACKING() duplicates that
  result through otelc_dbg_memdup() and frees the original, so error strings
  participate in leak tracking like any other tracked block; errno is preserved
  across the exchange.

Coverage boundary:

  Only allocations made through the OTELC_* macros are tracked.  The external
  allocator hooks default to the tracked functions, so span and span context
  structures stay covered until a caller registers its own malloc/free pair
  through otelc_ext_init(), which bypasses the tracker.  The C++ objects are
  not tracked at all: the impl structures and the handle objects are allocated
  with the nothrow helpers and released with delete, the wrapper-created SDK
  objects are released through their smart pointers, and the SDK performs its
  internal allocations itself.  The handle objects are instead accounted by
  the handle-map counters; otelc_statistics_check() verifies the live map size
  together with the id, alloc_fail_cnt, erase_cnt and destroy_cnt counters in
  the test suite, while peak_size is printed by otelc_statistics() and the debug
  handle-map dumps but never verified.