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

# Monitoring JVM metrics with ClickStack

> Monitoring JVM with ClickStack

export const TrackedLink = ({href, eventName, children, ...rest}) => {
  const handleClick = () => {
    try {
      if (typeof window !== "undefined" && window.galaxy && eventName) {
        window.galaxy.track(eventName, {
          interaction: "click"
        });
      }
    } catch (e) {}
  };
  return <a href={href} onClick={handleClick} {...rest}>
      {children}
    </a>;
};

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

<Info>
  **TL;DR**

  Monitor JVM applications in ClickStack using the OpenTelemetry Java agent. Includes a demo dataset and pre-built dashboard.
</Info>

<h2 id="existing-jvm">
  Integration with existing JVM application
</h2>

This section covers configuring your existing JVM application to send metrics to ClickStack using the OpenTelemetry Java agent.

If you would like to test the integration before configuring your production setup, you can test with our demo dataset in the [demo dataset section](#demo-dataset).

<h5 id="prerequisites">
  Prerequisites
</h5>

* ClickStack instance running
* Existing Java application (Java 8+)
* Access to modify JVM startup arguments

<Steps>
  <Step>
    <h4 id="get-api-key">
      Get ClickStack API key
    </h4>

    The OpenTelemetry Java agent sends data to ClickStack's OTLP endpoint, which requires authentication.

    1. Open HyperDX at your ClickStack URL (e.g., [http://localhost:8080](http://localhost:8080))
    2. Create an account or log in if needed
    3. Navigate to **Team Settings → API Keys**
    4. Copy your **Ingestion API Key**

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/Y9kcWM6RbYppspJn/images/clickstack/api-key.png?fit=max&auto=format&n=Y9kcWM6RbYppspJn&q=85&s=cbaa2d8bdf8332b6fe2ae42eec793c77" alt="ClickStack API Key" width="3810" height="1924" data-path="images/clickstack/api-key.png" />
  </Step>

  <Step>
    <h4 id="download-agent">
      Download OpenTelemetry Java agent
    </h4>

    Download the OpenTelemetry Java agent JAR file:

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

    This downloads the agent to your current directory. You can place it wherever makes sense for your deployment (e.g., `/opt/opentelemetry/` or alongside your application JAR).
  </Step>

  <Step>
    <h4 id="configure-jvm">
      Configure JVM startup arguments
    </h4>

    Add the Java agent to your JVM startup command. The agent automatically collects JVM metrics and sends them to ClickStack.

    <h5 id="command-line-flags">
      Option 1: Command line flags
    </h5>

    ```bash theme={null}
    java -javaagent:opentelemetry-javaagent.jar \
      -Dotel.service.name=my-java-app \
      -Dotel.exporter.otlp.endpoint=http://localhost:4318 \
      -Dotel.exporter.otlp.protocol=http/protobuf \
      -Dotel.exporter.otlp.headers="authorization=YOUR_API_KEY" \
      -Dotel.metrics.exporter=otlp \
      -Dotel.logs.exporter=none \
      -Dotel.traces.exporter=none \
      -jar my-application.jar
    ```

    **Replace the following:**

    * `opentelemetry-javaagent.jar` → Full path to the agent JAR (e.g., `/opt/opentelemetry/opentelemetry-javaagent.jar`)
    * `my-java-app` → A meaningful name for your service (e.g., `payment-service`, `user-api`)
    * `YOUR_API_KEY` → Your ClickStack API key from the command above
    * `my-application.jar` → Your application's JAR file name
    * `http://localhost:4318` → Your ClickStack endpoint (use `localhost:4318` if ClickStack runs on the same machine, otherwise use `http://your-clickstack-host:4318`)

    <h5 id="env-vars">
      Option 2: Environment variables
    </h5>

    Alternatively, use environment variables:

    ```bash theme={null}
    export JAVA_TOOL_OPTIONS="-javaagent:opentelemetry-javaagent.jar"
    export OTEL_SERVICE_NAME="my-java-app"
    export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
    export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
    export OTEL_EXPORTER_OTLP_HEADERS="authorization=YOUR_API_KEY"
    export OTEL_METRICS_EXPORTER="otlp"
    export OTEL_LOGS_EXPORTER="none"
    export OTEL_TRACES_EXPORTER="none"

    java -jar my-application.jar
    ```

    **Replace the following:**

    * `opentelemetry-javaagent.jar` → Full path to the agent JAR
    * `my-java-app` → Your service name
    * `YOUR_API_KEY` → Your ClickStack API key
    * `http://localhost:4318` → Your ClickStack endpoint
    * `my-application.jar` → Your application's JAR file name

    <Tip>
      The OpenTelemetry Java agent automatically collects these JVM metrics:

      * **Memory**: `jvm.memory.used`, `jvm.memory.limit`, `jvm.memory.committed`, `jvm.memory.used_after_last_gc`
      * **Garbage Collection**: `jvm.gc.duration`
      * **Threads**: `jvm.thread.count`
      * **Classes**: `jvm.class.count`, `jvm.class.loaded`, `jvm.class.unloaded`
      * **CPU**: `jvm.cpu.time`, `jvm.cpu.count`
    </Tip>
  </Step>

  <Step>
    <h4 id="verifying-metrics">
      Verify metrics in HyperDX
    </h4>

    Once your application is running with the agent, verify metrics are flowing to ClickStack:

    1. Open HyperDX at [http://localhost:8080](http://localhost:8080) (or your ClickStack URL)
    2. Navigate to **Chart Explorer**
    3. Search for metrics starting with `jvm.` (e.g., `jvm.memory.used`, `jvm.gc.duration`, `jvm.thread.count`)
  </Step>
</Steps>

<h2 id="demo-dataset">
  Demo dataset
</h2>

For users who want to test the JVM metrics integration before instrumenting their applications, we provide a sample dataset with pre-generated metrics showing realistic JVM behavior from a medium-sized microservice with steady moderate traffic.

<Steps>
  <Step>
    <h4 id="download-sample">
      Download the sample dataset
    </h4>

    ```bash theme={null}
    # Download gauge metrics (memory, threads, CPU, classes)
    curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/jvm/jvm-metrics-gauge.jsonl

    # Download sum metrics (GC events)
    curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/jvm/jvm-metrics-sum.jsonl
    ```

    The dataset includes 24 hours of JVM metrics showing:

    * Heap memory growth with periodic garbage collection events
    * Thread count variations
    * Realistic GC pause times
    * Class loading activity
    * CPU utilization patterns
  </Step>

  <Step>
    <h4 id="start-clickstack">
      Start ClickStack
    </h4>

    If you don't already have ClickStack running:

    ```bash theme={null}
    docker run -d --name clickstack \
      -p 8080:8080 -p 4317:4317 -p 4318:4318 \
      clickhouse/clickstack-all-in-one:latest
    ```

    Wait a few moments for ClickStack to fully start up.
  </Step>

  <Step>
    <h4 id="import-demo-data">
      Import the demo dataset
    </h4>

    ```bash theme={null}
    # Import gauge metrics (memory, threads, CPU, classes)
    docker exec -i clickstack clickhouse-client --query="
      INSERT INTO default.otel_metrics_gauge FORMAT JSONEachRow
    " < jvm-metrics-gauge.jsonl

    # Import sum metrics (GC events)
    docker exec -i clickstack clickhouse-client --query="
      INSERT INTO default.otel_metrics_sum FORMAT JSONEachRow
    " < jvm-metrics-sum.jsonl
    ```

    This imports the metrics directly into ClickStack's metrics tables.
  </Step>

  <Step>
    <h4 id="verify-demo-metrics">
      Verify the demo data
    </h4>

    Once imported:

    1. Open HyperDX at [http://localhost:8080](http://localhost:8080) and log in (create an account if needed)
    2. Navigate to the Search view and set source to **Metrics**
    3. Set the time range to **2025-12-06 14:00:00 - 2025-12-09 14:00:00**
    4. Search for `jvm.memory.used` or `jvm.gc.duration`

    You should see metrics for the demo service.

    <Info>
      **Timezone Display**

      HyperDX displays timestamps in your browser's local timezone. The demo data spans **2025-12-07 14:00:00 - 2025-12-08 14:00:00 (UTC)**. Set your time range to **2025-12-06 14:00:00 - 2025-12-09 14:00:00** to ensure you see the demo metrics regardless of your location. Once you see the metrics, you can narrow the range to a 24-hour period for clearer visualizations.
    </Info>
  </Step>
</Steps>

<h2 id="dashboards">
  Dashboards and visualization
</h2>

To help you monitor JVM applications with ClickStack, we provide a pre-built dashboard with essential visualizations for JVM metrics.

<Steps>
  <Step>
    <h4 id="download">
      <TrackedLink href={'/examples/jvm-metrics-dashboard.json'} download="jvm-metrics-dashboard.json" eventName="docs.kafka_metrics_monitoring.dashboard_download">Download</TrackedLink> the dashboard configuration
    </h4>
  </Step>

  <Step>
    <h4 id="import-dashboard">
      Import the pre-built dashboard
    </h4>

    1. Open HyperDX and navigate to the Dashboards section
    2. Click **Import Dashboard** in the upper right corner under the ellipses

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/zXCQbzXFHfeD9FBK/images/clickstack/import-dashboard.png?fit=max&auto=format&n=zXCQbzXFHfeD9FBK&q=85&s=eace17d7f86efbec4d3151bbf428941a" alt="Import dashboard button" width="3024" height="556" data-path="images/clickstack/import-dashboard.png" />

    3. Upload the `jvm-metrics-dashboard.json` file and click **Finish Import**

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/zXCQbzXFHfeD9FBK/images/clickstack/jvm/jvm-metrics-import.png?fit=max&auto=format&n=zXCQbzXFHfeD9FBK&q=85&s=18fcf770c3c41b34c37ad94be0cb6dcc" alt="Finish import" width="3812" height="1902" data-path="images/clickstack/jvm/jvm-metrics-import.png" />
  </Step>

  <Step>
    <h4 id="created-dashboard">
      View the dashboard
    </h4>

    The dashboard will be created with all visualizations pre-configured:

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/zXCQbzXFHfeD9FBK/images/clickstack/jvm/jvm-metrics-dashboard.png?fit=max&auto=format&n=zXCQbzXFHfeD9FBK&q=85&s=1c449548de372510522b6e9c9d269108" alt="Kafka Metrics dashboard" width="3812" height="1902" data-path="images/clickstack/jvm/jvm-metrics-dashboard.png" />

    <Note>
      For the demo dataset, set the time range to **2025-12-07 14:00:00 - 2025-12-08 14:00:00 (UTC)**. Adjust based on your local timezone.
    </Note>
  </Step>
</Steps>

<h2 id="troubleshooting">
  Troubleshooting
</h2>

<h3 id="troubleshooting-not-loading">
  Agent not starting
</h3>

**Verify the agent JAR exists:**

```bash theme={null}
ls -lh /path/to/opentelemetry-javaagent.jar
```

**Check Java version compatibility (requires Java 8+):**

```bash theme={null}
java -version
```

**Look for agent startup log message:**
When your application starts, you should see:

```text theme={null}
[otel.javaagent] OpenTelemetry Javaagent v2.22.0 started
```

<h3 id="no-metrics">
  No metrics appearing in HyperDX
</h3>

**Verify ClickStack is running and accessible:**

```bash theme={null}
docker ps | grep clickstack
curl -v http://localhost:4318/v1/metrics
```

**Check that metrics exporter is configured:**

```bash theme={null}
# If using environment variables, verify:
echo $OTEL_METRICS_EXPORTER
# Should output: otlp
```

**Check application logs for OpenTelemetry errors:**
Look for any error messages related to OpenTelemetry or OTLP export failures in your application logs.

**Verify network connectivity:**
If ClickStack is on a remote host, ensure port 4318 is accessible from your application server.

**Verify agent version:**
Ensure you're using the latest stable agent version (currently 2.22.0), as newer versions often include performance improvements.

<h2 id="next-steps">
  Next steps
</h2>

* Set up [alerts](/clickstack/features/alerts) for critical metrics like high heap usage, frequent GC pauses, or thread exhaustion
* Explore [other ClickStack integrations](/clickstack/integration-examples/index) to unify your observability data

<h2 id="going-to-production">
  Going to production
</h2>

This guide demonstrates configuring the OpenTelemetry Java agent for local testing. For production deployments, include the agent JAR in your container images and configure via environment variables for easier management. For larger environments with many JVM instances, deploy a centralized OpenTelemetry Collector to batch and forward metrics from multiple applications instead of sending directly to ClickStack.

See [Ingesting with OpenTelemetry](/clickstack/ingesting-data/opentelemetry) for production deployment patterns and collector configuration examples.