Grafana Integration
Setup
These instructions are for a local Grafana setup which you can run using docker-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.
|
Start by cloning the observability-grafana-setup
repository:
git clone https://github.com/vaadin/observability-grafana-setup.git
From the setup folder, run:
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.
Observability Kit Configuration
To configure Observability Kit, create an agent.properties
file with the following content:
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:
otel.exporter.otlp.endpoint=https://collector.my-domain.net:4317
Running the App
Run the application using the Java binary and pass the respective arguments for the Java agent and the agent configuration:
java -javaagent:PATH/TO/vaadin-opentelemetry-javaagent-VERSION.jar \
-Dotel.javaagent.configuration-file=PATH/TO/agent.properties \
-jar myapp.jar
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.
|
Viewing Data
The Grafana setup provides a sample dashboard 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.
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 for more information on how to use the Explore view.
Viewing Traces
To view traces, open the Explore view, 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.
Viewing Metrics
To view metrics, open the Explore view, 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.
Viewing Logs
To view logs, open the Explore view, 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: vaadin
by default.
Then click the refresh button in the top-right to search for logs.