# Java

Instrument Java applications with OpenTelemetry

# Integration

Instrument your Java applications to send traces to Kopai using the OpenTelemetry Java agent.

## Java Agent (Recommended)

The [OpenTelemetry Java agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation) provides **zero-code instrumentation** - no code changes required.

### Download the Agent

```bash
curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
```

### Running Your Application

Set environment variables and run with the agent:

```bash
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-http.kopai.app"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer YOUR_TOKEN"
export OTEL_SERVICE_NAME="my-java-service"

java -javaagent:opentelemetry-javaagent.jar -jar your-app.jar
```

| Variable | Description |
|----------|-------------|
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Kopai OTLP endpoint |
| `OTEL_EXPORTER_OTLP_HEADERS` | Auth header with your backend token |
| `OTEL_SERVICE_NAME` | Name shown in Kopai UI |

## Auto-Instrumentation

The Java agent automatically instruments:

- **HTTP** - Spring MVC, JAX-RS, Servlet, Netty, OkHttp
- **Databases** - JDBC, Hibernate, MongoDB, Redis, Cassandra
- **Messaging** - Kafka, RabbitMQ, JMS
- **Frameworks** - Spring Boot, Quarkus, Micronaut, Vert.x
- **Runtime** - JVM metrics, garbage collection, thread pools

See the [full list of supported libraries](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md).

## Working Example

For a complete working example:

**[Java Example](https://github.com/kopai-app/kopai-integration-examples/tree/main/java)**

## Troubleshooting

### No traces appearing

1. Verify the agent is loaded: look for `[otel.javaagent]` in startup logs
2. Check `OTEL_EXPORTER_OTLP_ENDPOINT` is set correctly
3. Verify token in `OTEL_EXPORTER_OTLP_HEADERS`

### Agent not attaching

- Ensure `-javaagent` flag comes **before** `-jar`
- Check Java version: agent requires Java 8+

### Debug logging

Enable agent debug logs:

```bash
export OTEL_JAVAAGENT_DEBUG=true
```

## References

- [OpenTelemetry Java Getting Started](https://opentelemetry.io/docs/languages/java/getting-started/)
- [Java Agent Releases](https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases)
- [Supported Libraries](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md)
- [SDK Configuration](https://opentelemetry.io/docs/languages/sdk-configuration/)