Package com.ants.platform.tracing

Class Ants

java.lang.Object

com.ants.platform.tracing.Ants

public final class Ants
extends Object

High-level entry point for Agentic Ants tracing, mirroring the JS startObservation / startActiveObservation / observe / updateActiveTrace surface.

Call AntsPlatformOtel.configure(com.ants.platform.otel.AntsPlatformSpanProcessor.Builder) once at startup, then:

 Ants.startActiveObservation("research-agent", ObservationType.AGENT, agent -> {
     agent.input(question);
     agent.updateTrace(TraceAttributes.builder().name("research").userId("u1").build());

     AntsGeneration gen = Ants.startGeneration("draft-answer")
         .model("gpt-4o-mini").input(question);
     gen.output(answer).usage(120, 80).end();

     AntsObservation tool = Ants.startObservation("web-search", ObservationType.TOOL);
     tool.input(query).output(results).end();

     agent.output(answer);
 });
 AntsPlatformOtel.flush();
 

Method Summary

Modifier and Type	Method	Description
static AntsObservation	currentObservation()	Returns a fluent view over the currently active span, or null if none.
static <T> T	observe(String name, ObservationType type, Function<AntsObservation,T> fn)	Runs fn with a new active observation and returns its result.
static <T> T	observeGeneration(String name, Function<AntsGeneration,T> fn)	observe(java.lang.String, com.ants.platform.tracing.ObservationType, java.util.function.Function<com.ants.platform.tracing.AntsObservation, T>) for generations.
static void	startActiveGeneration(String name, Consumer<AntsGeneration> fn)	Active variant for generations.
static void	startActiveObservation(String name, ObservationType type, Consumer<AntsObservation> fn)	Runs fn with a new observation set as the active span, so any observations created inside nest under it automatically.
static AntsGeneration	startGeneration(String name)	Starts a generation, nested under the current active span if any.
static AntsGeneration	startGeneration(String name, AntsObservation parent)	Starts a generation explicitly parented to parent.
static AntsObservation	startObservation(String name)	Starts a span, nested under the current active span if any.
static AntsObservation	startObservation(String name, ObservationType type)	Starts an observation of the given type, nested under the current active span if any.
static AntsObservation	startObservation(String name, ObservationType type, AntsObservation parent)	Starts an observation explicitly parented to parent.
static io.opentelemetry.api.trace.Tracer	tracer()	The Ants OpenTelemetry tracer (from the globally-registered provider).
static void	updateActiveTrace(TraceAttributes attrs)	Sets trace-level attributes on the currently active span.

Methods inherited from class java.lang.Object

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

Method Details

tracer

public static io.opentelemetry.api.trace.Tracer tracer()

The Ants OpenTelemetry tracer (from the globally-registered provider).

startObservation

public static AntsObservation startObservation(String name)

Starts a span, nested under the current active span if any.

startObservation

public static AntsObservation startObservation(String name,
 ObservationType type)

Starts an observation of the given type, nested under the current active span if any.

startObservation

public static AntsObservation startObservation(String name,
 ObservationType type,
 AntsObservation parent)

Starts an observation explicitly parented to parent.

startGeneration

public static AntsGeneration startGeneration(String name)

Starts a generation, nested under the current active span if any.

startGeneration

public static AntsGeneration startGeneration(String name,
 AntsObservation parent)

Starts a generation explicitly parented to parent.

startActiveObservation

public static void startActiveObservation(String name,
 ObservationType type,
 Consumer<AntsObservation> fn)

Runs fn with a new observation set as the active span, so any observations created inside nest under it automatically. The span is ended when fn returns (or throws, recording the error).

startActiveGeneration

public static void startActiveGeneration(String name,
 Consumer<AntsGeneration> fn)

Active variant for generations.

observe

public static <T> T observe(String name,
 ObservationType type,
 Function<AntsObservation,T> fn)

Runs fn with a new active observation and returns its result. Ends the span on completion; on exception, records the error and rethrows.

observeGeneration

public static <T> T observeGeneration(String name,
 Function<AntsGeneration,T> fn)

observe(java.lang.String, com.ants.platform.tracing.ObservationType, java.util.function.Function<com.ants.platform.tracing.AntsObservation, T>) for generations.

updateActiveTrace

public static void updateActiveTrace(TraceAttributes attrs)

Sets trace-level attributes on the currently active span.

currentObservation

public static AntsObservation currentObservation()

Returns a fluent view over the currently active span, or null if none.