---
title: Getting started
weight: 1
cSpell:ignore: Dotel myapp
---

## Setup

1.  Download [opentelemetry-javaagent.jar][] from [Releases][] of the
    `opentelemetry-java-instrumentation` repository and place the JAR in your
    preferred directory. The JAR file contains the agent and instrumentation
    libraries.
2.  Add `-javaagent:path/to/opentelemetry-javaagent.jar` and other config to
    your JVM startup arguments and launch your app:

    - Directly on the startup command:

      ```shell
      java -javaagent:path/to/opentelemetry-javaagent.jar -Dotel.service.name=your-service-name -jar myapp.jar
      ```

    - Via the `JAVA_TOOL_OPTIONS` and other environment variables:

      ```shell
      export JAVA_TOOL_OPTIONS="-javaagent:path/to/opentelemetry-javaagent.jar"
      export OTEL_SERVICE_NAME="your-service-name"
      java -jar myapp.jar
      ```

## Configuring the agent

The agent is highly configurable.

One option is to pass configuration properties via the `-D` flag. In this
example, a service name and Zipkin exporter for traces are configured:

```sh
java -javaagent:path/to/opentelemetry-javaagent.jar \
     -Dotel.service.name=your-service-name \
     -Dotel.traces.exporter=zipkin \
     -jar myapp.jar
```

You can also use environment variables to configure the agent:

```sh
OTEL_SERVICE_NAME=your-service-name \
OTEL_TRACES_EXPORTER=zipkin \
java -javaagent:path/to/opentelemetry-javaagent.jar \
     -jar myapp.jar
```

You can also supply a Java properties file and load configuration values from
there:

```sh
java -javaagent:path/to/opentelemetry-javaagent.jar \
     -Dotel.javaagent.configuration-file=path/to/properties/file.properties \
     -jar myapp.jar
```

or

```sh
OTEL_JAVAAGENT_CONFIGURATION_FILE=path/to/properties/file.properties \
java -javaagent:path/to/opentelemetry-javaagent.jar \
     -jar myapp.jar
```

To see the full range of configuration options, see
[Agent Configuration](../configuration).

## Supported libraries, frameworks, application services, and JVMs

The Java agent ships with instrumentation libraries for many popular components.
For the full list, see [Supported libraries, frameworks, application services,
and JVMs][support].

## Troubleshooting

{{% config_option name="otel.javaagent.debug" %}}

Set to `true` to see debug logs. Note that these are quite verbose.

{{% /config_option %}}

## Next steps

After you have automatic instrumentation configured for your app or service, you
might want to [annotate](../annotations) selected methods or add
[manual instrumentation](/docs/languages/java/instrumentation/) to collect
custom telemetry data.

[opentelemetry-javaagent.jar]:
  https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
[releases]:
  https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases
[support]:
  https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md
