Class Observability

java.lang.Object
org.j7m.middleware.integrations.Observability
All Implemented Interfaces:
AutoCloseable
public final class Observability extends Object implements AutoCloseable
Concrete W3C/OpenTelemetry propagation, bounded OTLP/HTTP JSON export and Prometheus scrape. Application operations never wait for the collector. Only fixed operation names and numeric diagnostics are exported: no application payloads, principals, tokens, keys, baggage or vendor tracestate are exported. Instances are thread-safe; span scopes must close on their creating thread.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    final class 
    Observability.DetachedSpan
    Thread-safe application span lifetime.
    static enum 
    Observability.Operation
    Fixed low-cardinality operation vocabulary.
    final class 
    Observability.SpanScope
    Thread-confined span lifetime.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Observability(URI collector, InetSocketAddress scrape, int capacity)
    Starts a concrete exporter and bounded scrape endpoint.

  • Method Summary

    Modifier and Type
    Method
    Description
    InetSocketAddress
    address()
    Exposes the actual scrape address.
    io.opentelemetry.context.Scope
    attach(org.j7m.middleware.distributed.TraceCarrier carrier)
    Attaches extracted remote context for callbacks on the current thread.
    int
    buffered()
    Returns bounded exporter occupancy for health diagnostics.
    int
    capacity()
    Returns the configured queue limit.
    org.j7m.middleware.distributed.TraceCarrier
    capture()
    Captures the current official OpenTelemetry context without baggage.
    void
    close()
    Stops telemetry without waiting for an unavailable collector; queued spans are counted dropped.
    long
    dropped()
    Returns the cumulative number of spans discarded on overload/collector failure.
    org.j7m.middleware.distributed.ExecutionClient.Observer
    executionObserver()
    Supplies automatic trace lifetimes for the production execution RPC/job/saga facades.
    org.j7m.middleware.distributed.PartitionEndpoint
    observe(org.j7m.middleware.distributed.PartitionEndpoint endpoint)
    Wraps a real partition transport and observes committed migration/status responses.
    <T> T
    runJob(org.j7m.middleware.distributed.ExecutionResult claimed, Callable<T> callback)
    Executes a claimed job callback under the original persisted producer context.
    String
    scrape()
    Produces Prometheus text with a fixed vocabulary and no user-controlled labels.
    Observability.SpanScope
    start(Observability.Operation operation)
    Starts a child of the current thread's context.
    Observability.SpanScope
    start(Observability.Operation operation, org.j7m.middleware.distributed.TraceCarrier parent)
    Starts an interoperable child span using an explicit parent.
    Observability.DetachedSpan
    startDetached(Observability.Operation operation, org.j7m.middleware.distributed.TraceCarrier parent)
    Creates a thread-safe span lifetime independent of individual context attachment scopes.
    AutoCloseable
    watchConsensus(org.j7m.middleware.consensus.NetworkConsensusNode node)
    Registers real group progress and periodically tests quorum outside data/scrape paths.
    AutoCloseable
    watchExecution(org.j7m.middleware.distributed.ExecutionClient client)
    Polls real scope-authorized execution counters without exporting identities.
    AutoCloseable
    watchLease(org.j7m.middleware.distributed.ResourceEndpoint endpoint, String key)
    Registers real lease observations without exporting the resource key or owner.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Observability

      public Observability(URI collector, InetSocketAddress scrape, int capacity) throws IOException
      Starts a concrete exporter and bounded scrape endpoint.
      Parameters:
      collector - OTLP traces endpoint including /v1/traces; HTTPS or loopback HTTP
      scrape - bind address for /metrics, port zero selects a free port
      capacity - maximum queued spans in [1,65536]; one further export batch is bounded to 32
      Throws:
      IOException - for scrape bind failure
      IllegalArgumentException - for unsafe endpoint or invalid bounds

  • Method Details

    • capture

      public org.j7m.middleware.distributed.TraceCarrier capture()
      Captures the current official OpenTelemetry context without baggage.
      Returns:
      bounded W3C carrier

    • attach

      public io.opentelemetry.context.Scope attach(org.j7m.middleware.distributed.TraceCarrier carrier)
      Attaches extracted remote context for callbacks on the current thread.
      Parameters:
      carrier - validated W3C context
      Returns:
      scope that restores the previous thread context when closed

    • start

      public Observability.SpanScope start(Observability.Operation operation, org.j7m.middleware.distributed.TraceCarrier parent)
      Starts an interoperable child span using an explicit parent.
      Parameters:
      operation - fixed non-sensitive operation name
      parent - remote/persisted parent carrier, or empty to start a trace
      Returns:
      active span scope; close it to enqueue export

    • start

      public Observability.SpanScope start(Observability.Operation operation)
      Starts a child of the current thread's context.
      Parameters:
      operation - fixed non-sensitive operation
      Returns:
      active span scope

    • startDetached

      public Observability.DetachedSpan startDetached(Observability.Operation operation, org.j7m.middleware.distributed.TraceCarrier parent)
      Creates a thread-safe span lifetime independent of individual context attachment scopes. Each attachment must be closed on its creating thread; end may run on the physical completion worker.
      Parameters:
      operation - fixed low-cardinality operation
      parent - validated parent carrier
      Returns:
      owned span handle; export is nonblocking and bounded when ended

    • executionObserver

      public org.j7m.middleware.distributed.ExecutionClient.Observer executionObserver()
      Supplies automatic trace lifetimes for the production execution RPC/job/saga facades. Configure the same client with () -> capture().asMap() as its carrier supplier. Business fingerprints exclude propagation metadata, so a new retry span never changes work identity.
      Returns:
      nonblocking observer using only fixed operation names

    • runJob

      public <T> T runJob(org.j7m.middleware.distributed.ExecutionResult claimed, Callable<T> callback) throws Exception
      Executes a claimed job callback under the original persisted producer context. This helper does not acknowledge/complete the job: the worker must separately commit its result and protected effects through DurableJobs using the current ownership fence.
      Type Parameters:
      T - application result type
      Parameters:
      claimed - actual durable RUNNING job claim
      callback - application job work; payloads and exception messages are never exported
      Returns:
      callback result
      Throws:
      Exception - if validation or application execution fails

    • watchExecution

      public AutoCloseable watchExecution(org.j7m.middleware.distributed.ExecutionClient client)
      Polls real scope-authorized execution counters without exporting identities.
      Parameters:
      client - authenticated execution client
      Returns:
      observation cancellation handle

    • watchConsensus

      public AutoCloseable watchConsensus(org.j7m.middleware.consensus.NetworkConsensusNode node)
      Registers real group progress and periodically tests quorum outside data/scrape paths.
      Parameters:
      node - hosted consensus group
      Returns:
      handle cancelling observation without closing the node

    • watchLease

      public AutoCloseable watchLease(org.j7m.middleware.distributed.ResourceEndpoint endpoint, String key)
      Registers real lease observations without exporting the resource key or owner.
      Parameters:
      endpoint - authorized lease endpoint
      key - resource key used only for the query, never a metric label
      Returns:
      handle cancelling this observation

    • observe

      public org.j7m.middleware.distributed.PartitionEndpoint observe(org.j7m.middleware.distributed.PartitionEndpoint endpoint)
      Wraps a real partition transport and observes committed migration/status responses.
      Parameters:
      endpoint - authorized local or remote partition transport
      Returns:
      instrumented transport with identical mutation semantics

    • address

      public InetSocketAddress address()
      Exposes the actual scrape address.
      Returns:
      bound host and port

    • buffered

      public int buffered()
      Returns bounded exporter occupancy for health diagnostics.
      Returns:
      queued spans, never above configured capacity

    • capacity

      public int capacity()
      Returns the configured queue limit.
      Returns:
      maximum queued spans

    • dropped

      public long dropped()
      Returns the cumulative number of spans discarded on overload/collector failure.
      Returns:
      dropped span count

    • scrape

      public String scrape()
      Produces Prometheus text with a fixed vocabulary and no user-controlled labels.
      Returns:
      numeric diagnostic exposition

    • close

      public void close()
      Stops telemetry without waiting for an unavailable collector; queued spans are counted dropped.
      Specified by:
      close in interface AutoCloseable