> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-3a82795f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Java SDK for ClickStack - The ClickHouse Observability Stack

# Java

ClickStack uses the OpenTelemetry standard for collecting telemetry data (logs and
traces). Traces are auto-generated with automatic instrumentation, so manual
instrumentation isn't required to get value out of tracing.

**This guide Integrates:**

<table>
  <tbody>
    <tr>
      <td className="pe-2">✅ Logs</td>
      <td className="pe-2">✅ Metrics</td>
      <td className="pe-2">✅ Traces</td>
    </tr>
  </tbody>
</table>

<h2 id="getting-started">
  Getting started
</h2>

<Note>
  At present, the integration is compatible exclusively with **Java 8+**
</Note>

<h3 id="download-opentelemetry-java-agent">
  Download OpenTelemetry Java agent
</h3>

Download [`opentelemetry-javaagent.jar`](https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar)
and place the JAR in your preferred directory. The JAR file contains the agent
and instrumentation libraries. You can also use the following command to
download the agent:

```shell theme={null}
curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
```

<h3 id="configure-environment-variables">
  Configure environment variables
</h3>

Afterwards you'll need to configure the following environment variables in your shell to ship telemetry to ClickStack via the OpenTelemetry collector:

<Tabs>
  <Tab title="Managed ClickStack">
    ```shell theme={null}
    export JAVA_TOOL_OPTIONS="-javaagent:PATH/TO/opentelemetry-javaagent.jar" \
    OTEL_EXPORTER_OTLP_ENDPOINT=https://your-otel-collector:4318 \
    OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
    OTEL_LOGS_EXPORTER=otlp \
    OTEL_SERVICE_NAME='<NAME_OF_YOUR_APP_OR_SERVICE>'
    ```
  </Tab>

  <Tab title="ClickStack Open Source">
    ```shell theme={null}
    export JAVA_TOOL_OPTIONS="-javaagent:PATH/TO/opentelemetry-javaagent.jar" \
    OTEL_EXPORTER_OTLP_ENDPOINT=https://your-otel-collector:4318 \
    OTEL_EXPORTER_OTLP_HEADERS='authorization=<YOUR_INGESTION_API_KEY>' \
    OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
    OTEL_LOGS_EXPORTER=otlp \
    OTEL_SERVICE_NAME='<NAME_OF_YOUR_APP_OR_SERVICE>'
    ```
  </Tab>
</Tabs>

*The `OTEL_SERVICE_NAME` environment variable is used to identify your service in the HyperDX app, it can be any name you want.*

The `OTEL_EXPORTER_OTLP_HEADERS` environment variable contains the API Key available via HyperDX app in `Team Settings → API Keys`.

<h3 id="run-the-application-with-otel-java-agent">
  Run the application with OpenTelemetry Java agent
</h3>

```shell theme={null}
java -jar target/<APPLICATION_JAR_FILE>
```

<br />

Read more about Java OpenTelemetry instrumentation here: [https://opentelemetry.io/docs/instrumentation/java/](https://opentelemetry.io/docs/instrumentation/java/)