> ## Documentation Index
> Fetch the complete documentation index at: https://arizeai-433a7140.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# LangChain4j Tracing

> How to use OpenInference instrumentation with LangChain4j and export traces to Arize Phoenix.

## Prerequisites

* Java 11 or higher
* (Optional) Phoenix API key if using auth

### Add Dependencies

Add the dependencies to your `build.gradle`:

```groovy theme={null}
dependencies {
    // OpenInference instrumentation
    implementation project(path: ':instrumentation:openinference-instrumentation-langchain4j')

    // LangChain4j
    implementation "dev.langchain4j:langchain4j:${langchain4jVersion}"
    implementation "dev.langchain4j:langchain4j-open-ai:${langchain4jVersion}"

    // OpenTelemetry
    implementation "io.opentelemetry:opentelemetry-sdk"
    implementation "io.opentelemetry:opentelemetry-exporter-otlp"
    implementation "io.opentelemetry:opentelemetry-exporter-logging"
}
```

## Setup Phoenix

<Tabs>
  <Tab title="Docker">
    **Pull latest Phoenix image from** [**Docker Hub**](https://hub.docker.com/r/arizephoenix/phoenix)**:**

    ```bash theme={null}
    docker pull arizephoenix/phoenix:latest
    ```

    **Run your containerized instance:**

    ```bash theme={null}
    docker run -p 6006:6006 -p 4317:4317 arizephoenix/phoenix:latest
    ```

    This command:

    * Exposes port 6006 for the Phoenix web UI
    * Exposes port 4317 for the OTLP gRPC endpoint (where traces are sent)

    For more info on using Phoenix with Docker, see [Docker](/docs/phoenix/self-hosting/deployment-options/docker).
  </Tab>

  <Tab title="Phoenix Cloud">
    **Sign up for Phoenix:**

    <Steps>
      <Step>
        Sign up for an Arize Phoenix account at [https://app.phoenix.arize.com/login](https://app.phoenix.arize.com/login)
      </Step>

      <Step>
        Click `Create Space`, then follow the prompts to create and launch your space.
      </Step>
    </Steps>

    **Set your Phoenix endpoint and API Key:**

    From your new Phoenix Space

    <Steps>
      <Step>
        Create your API key from the Settings page
      </Step>

      <Step>
        Copy your `Hostname` from the Settings page
      </Step>

      <Step>
        Set your endpoint and API key:

        ```bash theme={null}
        export PHOENIX_API_KEY = "your-phoenix-api-key"
        export PHOENIX_COLLECTOR_ENDPOINT = "your-phoenix-endpoint"
        ```
      </Step>
    </Steps>

    <Info>
      Having trouble finding your endpoint? Check out [Finding your Phoenix Endpoint](/docs/phoenix/resources/frequently-asked-questions/what-is-my-phoenix-endpoint)
    </Info>
  </Tab>
</Tabs>

<Warning>
  If you are using Phoenix Cloud, adjust the endpoint in the code below as needed.
</Warning>

## Configuration for Phoenix Tracing

```java expandable theme={null}
private static void initializeOpenTelemetry() {
        // Create resource with service name
        Resource resource = Resource.getDefault()
                .merge(Resource.create(Attributes.of(
                        AttributeKey.stringKey("service.name"), "langchain4j",
                        AttributeKey.stringKey(SEMRESATTRS_PROJECT_NAME), "langchain4j-project",
                        AttributeKey.stringKey("service.version"), "0.1.0")));

        String apiKey = System.getenv("PHOENIX_API_KEY");
        OtlpGrpcSpanExporterBuilder otlpExporterBuilder = OtlpGrpcSpanExporter.builder()
                .setEndpoint("http://localhost:4317") # adjust as needed
                .setTimeout(Duration.ofSeconds(2));
        OtlpGrpcSpanExporter otlpExporter = null;
        if (apiKey != null && !apiKey.isEmpty()) {
            otlpExporter = otlpExporterBuilder
                    .setHeaders(() -> Map.of("Authorization", String.format("Bearer %s", apiKey)))
                    .build();
        } else {
            logger.log(Level.WARNING, "Please set PHOENIX_API_KEY environment variable if auth is enabled.");
            otlpExporter = otlpExporterBuilder.build();
        }

        // Create tracer provider with both OTLP (for Phoenix) and console exporters
        tracerProvider = SdkTracerProvider.builder()
                .addSpanProcessor(BatchSpanProcessor.builder(otlpExporter)
                        .setScheduleDelay(Duration.ofSeconds(1))
                        .build())
                .addSpanProcessor(SimpleSpanProcessor.create(LoggingSpanExporter.create()))
                .setResource(resource)
                .build();

        // Build OpenTelemetry SDK
        OpenTelemetrySdk.builder()
                .setTracerProvider(tracerProvider)
                .setPropagators(ContextPropagators.create(W3CTraceContextPropagator.getInstance()))
                .buildAndRegisterGlobal();

        System.out.println("OpenTelemetry initialized. Traces will be sent to Phoenix at http://localhost:6006");
    }
}
```

## Run LangChain4j

By instrumenting your application, spans will be created whenever it is run and will be sent to the Phoenix server for collection.

```java expandable theme={null}
import io.openinference.instrumentation.langchain4j.LangChain4jInstrumentor;
import dev.langchain4j.model.openai.OpenAiChatModel;

initializeOpenTelemetry();

// Auto-instrument LangChain4j
LangChain4jInstrumentor.instrument();

// Use LangChain4j as normal - traces will be automatically created
OpenAiChatModel model = OpenAiChatModel.builder()
    .apiKey("your-openai-api-key")
    .modelName("gpt-4")
    .build();

String response = model.generate("What is the capital of France?");
```

<Success>
  Full example: [https://github.com/Arize-ai/openinference/tree/main/java/examples/langchain4j-example](https://github.com/Arize-ai/openinference/tree/main/java/examples/langchain4j-example)
</Success>

## Observe

Once configured, your traces will be automatically sent to Phoenix where you can:

* **Monitor Performance**: Track latency, throughput, and error rates
* **Analyze Usage**: View token usage, model performance, and cost metrics
* **Debug Issues**: Trace request flows and identify bottlenecks
* **Evaluate Quality**: Run evaluations on your LLM outputs

## Resources

<CardGroup>
  <Card title="Full Example" href="https://github.com/Arize-ai/openinference/tree/main/java/examples/langchain4j-example" icon="github" horizontal description="Complete tracing example" />

  <Card title="OpenInference package" href="https://central.sonatype.com/artifact/com.arize/openinference-instrumentation-langchain4j" icon="box" horizontal description="OpenInference Java package" />
</CardGroup>