diff --git a/README.md b/README.md index de24ee9..198af44 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,14 @@ Logging is supported with Logback and Log4j2 ## Getting Started +Follow these three steps to get started with Grafana OpenTelemetry: + +- [Add the Grafana OpenTelemetry Starter dependency](#step-1-add-the-grafana-opentelemetry-starter-dependency) +- [Configure the application](#step-2-configuration) +- [Observe the service in Application Observability](#step-3-observe-the-service-in-application-observability) + +### Step 1: Add the Grafana Opentelemetry Starter dependency + Add the following dependency to your `build.gradle` ```groovy @@ -33,9 +41,10 @@ implementation 'com.grafana:grafana-opentelemetry-starter:1.4.0' ``` -### Configuration +### Step 2: Configuration -Finally, configure your application.yaml (or application.properties) either for Grafana Cloud OTLP Gateway or Grafana Agent. +Next, configure your application either for [Grafana Cloud OTLP Gateway](#grafana-cloud-otlp-gateway) +or [Grafana Agent](#grafana-agent). #### Grafana Cloud OTLP Gateway @@ -45,27 +54,50 @@ The easiest setup is to use the Grafana Cloud OTLP Gateway, because you don't ne the telemetry data to Grafana Cloud. The Grafana Cloud OTLP Gateway is a managed service that is available in all Grafana Cloud plans. -If you're just getting started with Grafana Cloud, you can [sign up for permanent free plan](https://grafana.com/products/cloud/). +1. Sign in to [Grafana Cloud](https://grafana.com), register for a Free Grafana Cloud account if required. + +2. After successful login, the browser will navigate to the Grafana Cloud Portal page . + + A new account will most likely belong to one organization with one stack. + + If the account has access to multiple Grafana Cloud Organizations, select an organization from the + top left **organization dropdown**. + + If the organization has access to multiple Grafana Cloud Stacks, navigate to a stack from the **left side bar** + or the main **Stacks** list. + +3. With a stack selected, or in the single stack scenario, below **Manage your Grafana Cloud Stack**, + click **Configure** in the **OpenTelemetry** section: + + ![otel tile](https://grafana.com/media/docs/grafana-cloud/application-observability/opentelemetry-tile.png) -1. Click on "Details" button in the "Grafana" section on https://grafana.com/profile/org -2. Copy "Instance ID" and "Zone" into the application.yaml below -3. On the left side, click on "Security" and then on "API Keys" -4. Click on "Create API Key" (MetricsPublisher role) and copy the key into the application.yaml below +4. In the **Password / API Token** section, click on **Generate now** to create a new API token: + - Give the API token a name, for example `otel-java` + - Click on **Create token** + - Click on **Close** without copying the token + - Now the environment variables section is populated with all the necessary information to send telemetry data + to Grafana Cloud + - Click on **Copy to Clipboard** to copy the environment variables to the clipboard -application.yaml: + ![otel env vars](https://grafana.com/media/docs/grafana-cloud/application-observability/opentelemetry-env-vars.png) -```yaml -spring: - application: - name: demo-app +5. Come up with a **Service Name** to identify the service, for example `cart`, and copy it into the shell command + below. Use the `service.namespace` to group multiple services together. +6. Optional: add resource attributes to the shell command below: + - **deployment.environment**: Name of the deployment environment, for example `staging` or `production` + - **service.namespace**: A namespace to group similar services, for example using `service.namespace=shop` for a + `cart` and `fraud-detection` service would create `shop/cart` and `shop/fraud-detection` in Grafana Cloud + Application Observability with filtering capabilities for easier management + - **service.version**: The application version, to see if a new version has introduced a bug + - **service.instance.id**: The unique instance, for example the Pod name (a UUID is generated by default) -grafana: - otlp: - cloud: - zone: - instanceId: - apiKey: +```shell + +export OTEL_SERVICE_NAME= +export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=,service.namespace=,service.version= ``` + +Finally, [Observe the service in Application Observability](#step-3-observe-the-service-in-application-observability). #### Grafana Agent @@ -73,30 +105,44 @@ The Grafana Agent is a single binary that can be deployed as a sidecar or daemon in your network. It provides an endpoint where the application can send its telemetry data to. The telemetry data is then forwarded to Grafana Cloud or a Grafana OSS stack. -application.yaml: - -```yaml -spring: - application: - name: demo-app +> 💨 Skip this section and let the [OpenTelemetry Integration](https://grafana.com/docs/grafana-cloud/data-configuration/integrations/integration-reference/integration-opentelemetry/) +> create everything for you. + +1. If the Grafana Agent is not running locally or doesn't use the default grpc endpoint, + adjust OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_PROTOCOL (to `http/protobuf`). +2. Choose a **Service Name** to identify the service. +3. Optionally, add attributes to filter data: + - **deployment.environment**: Name of the deployment environment (`staging` or `production`) + - **service.namespace**: A namespace to group similar services + (e.g. `shop` would create `shop/cart` in Application Observability) + - **service.version**: The application version, to see if a new version has introduced a bug + - **service.instance.id**: The unique instance, for example the Pod name (a UUID is generated by default) + +```shell +export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 +export OTEL_EXPORTER_OTLP_PROTOCOL=grpc +export OTEL_SERVICE_NAME= +export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=,service.namespace=,service.version= ``` -- [How to configure the Grafana Agent](https://grafana.com/docs/opentelemetry/instrumentation/grafana-agent/) -- Refer to the [Properties section](#properties) for details about configuration properties - -If you have changed the configuration of the Grafana Agent, you can specify the endpoint and protocol explicitly. -This example uses the default values - it is equivalent to the example above: - -```yaml -spring: - application: - name: demo-app -grafana: - otlp: - onprem: - endpoint: http://localhost:4317 - protocol: grpc -``` +The application will send data to the Grafana Agent. Please follow the +[Grafana Agent configuration for OpenTelemetry](https://grafana.com/docs/opentelemetry/instrumentation/configuration/grafana-agent/) +guide. + +Finally, [Observe the service in Application Observability](#step-3-observe-the-service-in-application-observability). + +### Step 3: Observe the Service in Application Observability + +Finally, make some requests to the service to validate data is sent to Grafana Cloud. +It might take up to five minutes for data to appear. + +In Grafana, replace the path of the URL with `/a/grafana-app-observability-app/services` or: + +1. Click on the menu icon in the top left corner +2. Open the _Observability_ menu +3. Click on _Application_ + +**Important**: refer to the [troubleshooting guide](#troubleshooting) if there is no data in Application Observability. ### Grafana Dashboard