use the otel tile for easier setup and to avoid the deprecated api keys

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'
 </dependency>
 ```
 
-### 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,58 +54,95 @@ 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 <https://grafana.com/profile/org>.
+
+   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: <Grafana Zone>
-      instanceId: <Grafana Instance ID>
-      apiKey: <Grafana API key>
+```shell
+<Paste the environment variables from the previous section>
+export OTEL_SERVICE_NAME=<Service Name>
+export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=<Environment>,service.namespace=<Namespace>,service.version=<Version>
 ```
+                                                    
+Finally, [Observe the service in Application Observability](#step-3-observe-the-service-in-application-observability).
 
 #### Grafana Agent
 
 The Grafana Agent is a single binary that can be deployed as a sidecar or daemonset in Kubernetes, or as a service 
 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=<Service Name>
+export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=<Environment>,service.namespace=<Namespace>,service.version=<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