> Markdown version of [Grafana](https://vaadin.com/docs/v23/tools/observability/integrations/grafana). Section index: [llms.txt](https://vaadin.com/docs/v23/tools/llms.txt)

# Grafana Integration

## <a id="setup"></a>Setup

These instructions are for a local Grafana setup which you can run using [docker-compose](https://docs.docker.com/compose/). Alternatively, Grafana provides a managed hosting service for their products.

> **Caution: Not production-ready**
>
> The setup is intended for local testing only. It isn’t production ready. See the Grafana documentation on how to [configure and secure a self-hosted setup](https://grafana.com/docs/grafana/latest/setup-grafana/configure-security/).

Start by cloning the [`observability-grafana-setup`](https://github.com/vaadin/observability-grafana-setup) repository:

```terminal
git clone https://github.com/vaadin/observability-grafana-setup.git
```

From the setup folder, run:

```terminal
cd observability-grafana-setup
docker-compose up
```

This command starts a set of services for collecting and displaying data from Observability Kit:

- **Grafana Tempo** for collecting and storing traces;

- **Prometheus** for collecting and storing metrics;

- **Grafana Loki** for collecting and storing logs;

- **OpenTelemetry collector** for ingesting telemetry data from the agent, and distributing it to the services above; and

- **Grafana** for displaying traces, metrics and logs, also from the services above.

## <a id="configuration-file"></a>Observability Kit Configuration

To configure Observability Kit, create an `agent.properties` file with the following content:

agent.properties

```properties
otel.service.name=vaadin
otel.traces.exporter=otlp
otel.metrics.exporter=otlp
otel.logs.exporter=otlp
```

In the configuration above, the service name is defined as `vaadin`, which is also the default of the agent. The service name can be customized. Note, however, that the pre-configured Grafana dashboard queries data from the `vaadin` service, and needs to be edited when using a custom service name.

By default, the OpenTelemetry Protocol (OTLP) exporters assume that the OpenTelemetry collector is running locally. You don’t need to configure endpoints. If the collector is running on a different system, you need to configure an endpoint for the exporter:

agent.properties

```properties
otel.exporter.otlp.endpoint=https://collector.my-domain.net:4317
```

## <a id="running-the-app"></a>Running the App

Run the application using the Java binary and pass the respective arguments for the Java agent and the agent configuration:

**JAR file**

```terminal
java -javaagent:PATH/TO/vaadin-opentelemetry-javaagent-VERSION.jar \
     -Dotel.javaagent.configuration-file=PATH/TO/agent.properties \
     -jar myapp.jar
```

First create a file `setenv.bat` in your Tomcat installation’s `bin` folder. This script runs automatically with the startup script. Add the content from below to that file, but with your particular installation’s file paths. Then start Tomcat using `bin/startup.bat`.

**Tomcat (Windows)**

```terminal
set CATALINA_OPTS=%CATALINA_OPTS% -javaagent:PATH\TO\vaadin-opentelemetry-javaagent-VERSION.jar
set OTEL_JAVAAGENT_CONFIGURATION_FILE=PATH\TO\agent.properties
```

First create a file `setenv.sh` in your Tomcat installation’s `bin` folder. This script runs automatically with the startup script. Add the content from below to that file, but with your particular installation’s file paths. Then start Tomcat using `bin/startup.sh`.

**Tomcat (macOS/Linux)**

```terminal
export CATALINA_OPTS="$CATALINA_OPTS -javaagent:PATH/TO/vaadin-opentelemetry-javaagent-VERSION.jar"
export OTEL_JAVAAGENT_CONFIGURATION_FILE=PATH/TO/agent.properties
```

Start Jetty and pass the respective arguments for the Java agent and the agent configuration:

**Jetty**

```terminal
java -javaagent:PATH/TO/vaadin-opentelemetry-javaagent-VERSION.jar \
     -Dotel.javaagent.configuration-file=PATH/TO/agent.properties \
     -jar /PATH/TO/jetty_home/start.jar
```

If you want to run an application with the agent through Maven for testing purposes, set the `MAVEN_OPTS` variable as shown below. Then run your Maven goal, for example, `mvn jetty:run`.

**Maven (Windows)**

```terminal
set MAVEN_OPTS="-javaagent:PATH\TO\vaadin-opentelemetry-javaagent-VERSION.jar -Dotel.javaagent.configuration-file=PATH\TO\agent.properties"
```

If you want to run an application with the agent through Maven for testing purposes, set the `MAVEN_OPTS` variable as shown below. Then run your Maven goal, for example, `mvn jetty:run`.

**Maven (macOS/Linux)**

```terminal
export MAVEN_OPTS="-javaagent:PATH/TO/vaadin-opentelemetry-javaagent-VERSION.jar -Dotel.javaagent.configuration-file=PATH/TO/agent.properties"
```

> **Note: Replace placeholder paths and version**
>
> Remember to correct the path to the `agent.properties` file, as well as the path and version of the Observability Kit `.jar` file.

## <a id="viewing-data"></a>Viewing Data

The Grafana setup provides a [sample dashboard](http://localhost:3000/d/6_bNYpGVz/vaadin-dashboard?orgId=1) that shows basic metrics, like JVM memory usage and CPU usage, traces and errors, as well as logs. To log in, use the default credentials `admin` and `admin`.

> **Note: Remember to configure the service name**
>
> The service name needs to be configured as `vaadin` in the [configuration file](#configuration-file). Otherwise, the dashboard doesn’t show any data.

The individual panels of the dashboard may be used to explore the data in more detail. Click on a panel’s name to open the drop-down menu, and then click on **Explore**.

See the [Grafana documentation](https://grafana.com/docs/grafana/latest/explore/) for more information on how to use the [Explore view](http://localhost:3000/explore).

### <a id="viewing-traces"></a>Viewing Traces

To view traces, open the [Explore view](http://localhost:3000/explore), and select **Tempo** as the data source. Change the **Query type** to **Search**, and select the name of the service from the **Service name** menu. Then click the refresh button in the top-right to search for traces.

Use the **Tags** option to filter for specific span attributes. For example, to filter for traces that contains errors, enter `error=true`.

Clicking on a trace ID brings up a side panel that shows detailed information about a specific trace, such as nested spans, and their attributes and events.

### <a id="viewing-metrics"></a>Viewing Metrics

To view metrics, open the [Explore view](http://localhost:3000/explore), and select **Prometheus** as the data source. Select a metric from the **Metric** drop-down, for example, **process\_runtime\_jvm\_memory\_usage** to view JVM memory usage. Then click the refresh button in the top-right display the metric.

### <a id="viewing-logs"></a>Viewing Logs

To view logs, open the [Explore view](http://localhost:3000/explore), and select **Loki** as data source. Under **Labels**, configure a label for `service_name`, with the value that’s defined as service name in the [configuration file](#configuration-file): `vaadin` by default. Then click the refresh button in the top-right to search for logs.
