Java Annotation Tracing

plugins {
    id 'application'
}

repositories {
    mavenCentral()
}

dependencies {
    // OpenInference annotation instrumentor + semantic conventions
    implementation 'com.arize:openinference-instrumentation-annotation:0.1.2'
    implementation 'com.arize:openinference-semantic-conventions:0.1.12'

    // OpenTelemetry SDK + OTLP exporter
    implementation 'io.opentelemetry:opentelemetry-sdk:1.50.0'
    implementation 'io.opentelemetry:opentelemetry-exporter-otlp:1.50.0'
}

// Required: emits parameter names into the class file so the
// annotation agent can attach them as span attributes. Without this,
// parameters appear as `arg0`, `arg1`, ... in your spans.
compileJava {
    options.compilerArgs += '-parameters'
}

application {
    mainClass = 'example.Main'
}

export PHOENIX_COLLECTOR_ENDPOINT="http://localhost:6006"
export PHOENIX_PROJECT_NAME="annotation-tracing-example"
export OPENAI_API_KEY="<your-openai-api-key>"

# Only if your Phoenix instance has authentication enabled
# export PHOENIX_API_KEY="<your-phoenix-api-key>"

// src/main/java/example/Main.java
package example;

import com.arize.instrumentation.OITracer;
import com.arize.instrumentation.OpenInferenceAgent;
import com.arize.instrumentation.annotation.OpenInferenceAgentInstaller;
import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.api.trace.propagation.W3CTraceContextPropagator;
import io.opentelemetry.context.propagation.ContextPropagators;
import io.opentelemetry.exporter.otlp.http.trace.OtlpHttpSpanExporter;
import io.opentelemetry.exporter.otlp.http.trace.OtlpHttpSpanExporterBuilder;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.resources.Resource;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor;

import java.time.Duration;
import java.util.concurrent.TimeUnit;

public class Main {

    public static void main(String[] args) throws Exception {
        // Install the ByteBuddy agent BEFORE the JVM loads any annotated
        // class. QAService is first referenced further down in main(), so
        // installing here (as the first statement) is in time.
        OpenInferenceAgentInstaller.install();

        String endpoint = System.getenv().getOrDefault(
            "PHOENIX_COLLECTOR_ENDPOINT", "http://localhost:6006");
        String apiKey = System.getenv("PHOENIX_API_KEY");
        String project = System.getenv().getOrDefault(
            "PHOENIX_PROJECT_NAME", "annotation-tracing-example");

        // The openinference.project.name resource attribute selects the
        // Phoenix project that receives the traces.
        Resource resource = Resource.getDefault().merge(Resource.create(
            Attributes.of(
                AttributeKey.stringKey("service.name"), "annotation",
                AttributeKey.stringKey("openinference.project.name"),
                project)));

        // OTLP HTTP exporter pointed at the Phoenix collector.
        OtlpHttpSpanExporterBuilder exporterBuilder = OtlpHttpSpanExporter.builder()
            .setEndpoint(endpoint.replaceAll("/+$", "") + "/v1/traces");
        if (apiKey != null && !apiKey.isEmpty()) {
            exporterBuilder.addHeader("Authorization", "Bearer " + apiKey);
        }
        OtlpHttpSpanExporter exporter = exporterBuilder.build();

        SdkTracerProvider tracerProvider = SdkTracerProvider.builder()
            .addSpanProcessor(BatchSpanProcessor.builder(exporter)
                .setScheduleDelay(Duration.ofSeconds(1))
                .build())
            .setResource(resource)
            .build();

        OpenTelemetrySdk.builder()
            .setTracerProvider(tracerProvider)
            .setPropagators(ContextPropagators.create(
                W3CTraceContextPropagator.getInstance()))
            .buildAndRegisterGlobal();

        // The OITracer wraps the SDK tracer with OpenInference semantic
        // attribute handling. Register it on the global agent so every
        // annotated method routes its span through it.
        OITracer tracer = new OITracer(
            tracerProvider.get("com.arize.annotation"));
        OpenInferenceAgent.register(tracer);

        System.out.println("Phoenix tracing initialized for Annotations.");

        // First reference to QAService: class loading happens here,
        // safely AFTER OpenInferenceAgentInstaller.install() above.
        QAService service = new QAService();
        String answer = service.answer(
            "Why is the ocean salty? Answer in two sentences.");
        System.out.println(answer);

        // Flush and shut down before exit, or the JVM may exit before the
        // BatchSpanProcessor delivers its queue.
        tracerProvider.forceFlush().join(10, TimeUnit.SECONDS);
        tracerProvider.shutdown().join(10, TimeUnit.SECONDS);
        OpenInferenceAgent.unregister();
    }
}

// src/main/java/example/QAService.java
package example;

import com.arize.instrumentation.annotation.Agent;
import com.arize.instrumentation.annotation.Chain;
import com.arize.instrumentation.annotation.ExcludeFromSpan;
import com.arize.instrumentation.annotation.LLM;
import com.arize.instrumentation.annotation.Tool;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.Map;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class QAService {

    private static final HttpClient HTTP = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10))
        .build();

    @Agent(name = "qa-agent")
    public String answer(String question) {
        String context = retrieve(question);
        Map<String, Object> weather = getWeather("San Francisco");
        return generate(question, context, weather);
    }

    @Chain(name = "retriever")
    public String retrieve(String query) {
        return "OpenInference is an open standard for AI tracing.";
    }

    @Tool(name = "weather",
          description = "Gets current weather for a location")
    public Map<String, Object> getWeather(String location) {
        return Map.of("temp", 68, "condition", "foggy",
                      "location", location);
    }

    @LLM(name = "generator")
    public String generate(String question, String context,
                           @ExcludeFromSpan Map<String, Object> weather) {
        // @ExcludeFromSpan keeps the weather parameter out of the
        // captured input so the LLM span doesn't pick up unrelated
        // metadata that the language model never sees.
        String prompt = "Use this context to answer the question.\n"
                      + "Context: " + context + "\n\n"
                      + "Question: " + question;
        return openAiChatCompletion(prompt);
    }

    // Plain HTTPS call to OpenAI — no SDK with its own observability
    // hooks, so the only spans Phoenix receives are the annotation-driven
    // ones from @Agent / @Chain / @Tool / @LLM above.
    private String openAiChatCompletion(String prompt) {
        try {
            String body = "{\"model\":\"gpt-5.5\","
                + "\"messages\":[{\"role\":\"user\",\"content\":\""
                + jsonEscape(prompt) + "\"}]}";

            HttpRequest req = HttpRequest.newBuilder()
                .uri(URI.create("https://api.openai.com/v1/chat/completions"))
                .timeout(Duration.ofMinutes(3))
                .header("Authorization",
                        "Bearer " + System.getenv("OPENAI_API_KEY"))
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(body))
                .build();

            HttpResponse<String> resp = HTTP.send(req,
                HttpResponse.BodyHandlers.ofString());
            if (resp.statusCode() != 200) {
                throw new RuntimeException("OpenAI HTTP "
                    + resp.statusCode() + ": " + resp.body());
            }
            return extractContent(resp.body());
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

    // Minimal extractor — pulls "content":"..." out of the response
    // body. Replace with Jackson / Gson in production code.
    private static String extractContent(String json) {
        Matcher m = Pattern.compile(
            "\"content\"\\s*:\\s*\"((?:\\\\.|[^\"\\\\])*)\"")
            .matcher(json);
        if (!m.find()) {
            throw new RuntimeException("no content in: " + json);
        }
        return m.group(1)
            .replace("\\n", "\n")
            .replace("\\\"", "\"")
            .replace("\\\\", "\\");
    }

    private static String jsonEscape(String s) {
        return s.replace("\\", "\\\\")
                .replace("\"", "\\\"")
                .replace("\n", "\\n");
    }
}

gradle run

qa-agent (AGENT)
├── retriever (CHAIN)
├── weather (TOOL)
└── generator (LLM)