Update resource detection sample (#317)

* Update autoconf example documentation

* Update resource example

* Update readme for resource detection sample

Author: psx95

examples/autoconf/README.md

@@ -2,14 +2,56 @@
 
 An example application that sends custom traces+metric using *only* the OpenTelemetry API.  All SDK configuration is done using the autoconfiguration module.
 
-To spin it up on your own GKE cluster, run the following:
+### Prerequisites
+
+##### Get Google Cloud Credentials on your machine
+
+```shell
+gcloud auth application-default login
+```
+Executing this command will save your application credentials to default path which will depend on the type of machine -
+- Linux, macOS: `$HOME/.config/gcloud/application_default_credentials.json`
+- Windows: `%APPDATA%\gcloud\application_default_credentials.json`
+
+**NOTE: This method of authentication is not recommended for production environments.**
+
+Next, export the credentials to `GOOGLE_APPLICATION_CREDENTIALS` environment variable -
+
+For Linux & MacOS:
+```shell
+export GOOGLE_APPLICATION_CREDENTIALS=$HOME/.config/gcloud/application_default_credentials.json
+```
+
+For Windows:
+```shell
+SET GOOGLE_APPLICATION_CREDENTIALS=%APPDATA%\gcloud\application_default_credentials.json
+```
+
+##### Export the Google Cloud Project ID to `GOOGLE_CLOUD_PROJECT` environment variable:
+
+```shell
+export GOOGLE_CLOUD_PROJECT="my-awesome-gcp-project-id"
 ```
-export GOOGLE_CLOUD_PROJECT={your-project}
 
+## Running in Google Kubernetes Engine
+
+To spin it up on your own GKE cluster, run the following:
+```
 ./gradlew :examples-autoconf:jib --image="gcr.io/$GOOGLE_CLOUD_PROJECT/hello-autoconfigure-java"
 
 sed s/%GOOGLE_CLOUD_PROJECT%/$GOOGLE_CLOUD_PROJECT/g \
  examples/autoconf/job.yaml | kubectl apply -f -
 ```
 
-This will run a batch job which synthesizes a nested trace, latency metrics and exemplars.
+This will run a batch job which synthesizes a nested trace, latency metrics and exemplars.
+
+## Running locally on your machine
+
+In case you do not want to spin up your own GKE cluster, but still want telemetry to be published to Google Cloud, you can run the example locally.
+
+From the root of the repository,
+```shell
+cd examples/autoconf && gradle run
+```
+
+This will run the sample app locally on your machine, synthesizing a nested trace, latency metrics and exemplars.

examples/autoconf/build.gradle

@@ -28,6 +28,7 @@ dependencies {
 	runtimeOnly(libraries.opentelemetry_sdk_autoconf)
 	runtimeOnly(libraries.opentelemetry_sdk)
 	runtimeOnly project(':exporter-auto')
+	// Provides resources to the autoconfiguration module
 	runtimeOnly(libraries.opentelemetry_gcp_resources)
 }
 
@@ -38,6 +39,7 @@ def autoconf_config = [
 	'-Dotel.metrics.exporter=google_cloud_monitoring',
 	'-Dotel.logs.exporter=none',
 	'-Dotel.java.global-autoconfigure.enabled=true',
+	'-Dotel.service.name=example-autoconf-service',
 ]
 
 mainClassName = 'com.google.cloud.opentelemetry.example.autoconf.AutoconfExample'

examples/resource/README.md

@@ -1,13 +1,65 @@
 # Resource detection Example
 
-An example application that shows what resource attributes will be detected.
+> [!NOTE]
+> Running this example does not generate any telemetry. This example merely demonstrates resource attributes detetcted by the GCP Resource Detector.
 
-To spin it up on your own GKE cluster, run the following:
+An example application that shows what resource attributes will be detected by the [GCP Resource Detector](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/gcp-resources) and how the [Autoconfigure Resource Provider SPI](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure#resource-provider-spi) automatically *attaches* the detected resource attributes to the generated telemetry.
+
+### Prerequisites
+
+##### Get Google Cloud Credentials on your machine
+
+```shell
+gcloud auth application-default login
+```
+Executing this command will save your application credentials to default path which will depend on the type of machine -
+- Linux, macOS: `$HOME/.config/gcloud/application_default_credentials.json`
+- Windows: `%APPDATA%\gcloud\application_default_credentials.json`
+
+**NOTE: This method of authentication is not recommended for production environments.**
+
+Next, export the credentials to `GOOGLE_APPLICATION_CREDENTIALS` environment variable -
+
+For Linux & MacOS:
+```shell
+export GOOGLE_APPLICATION_CREDENTIALS=$HOME/.config/gcloud/application_default_credentials.json
+```
+
+For Windows:
+```shell
+SET GOOGLE_APPLICATION_CREDENTIALS=%APPDATA%\gcloud\application_default_credentials.json
+```
+
+##### Export the Google Cloud Project ID to `GOOGLE_CLOUD_PROJECT` environment variable:
+
+```shell
+export GOOGLE_CLOUD_PROJECT="my-awesome-gcp-project-id"
 ```
-export GOOGLE_CLOUD_PROJECT={your-project}
 
+## Running in Google Kubernetes Engine
+
+To spin it up on your own GKE cluster, run the following:
+```shell
 ./gradlew :examples-resource:jib --image="gcr.io/$GOOGLE_CLOUD_PROJECT/hello-resource-java"
 
 sed s/%GOOGLE_CLOUD_PROJECT%/$GOOGLE_CLOUD_PROJECT/g \
  examples/resource/job.yaml | kubectl apply -f -
-```
+```
+
+This will run the application as a GKE workload. You can view it from the `Workloads` tab under the `Resource Management` section on GKE console. 
+
+The generated logs can be viewed under the `Logs` tab on the `Job Details` page. These logs will show the detected resource attributes for GKE.
+
+## Running the application locally
+
+> [!NOTE]
+> Resource attributes won't be detected in unsupported environments. You can find a list of environments supported by the GCP detector [here](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/gcp-resources).
+
+You can run the application locally as well:
+
+From the root of the repository,
+```shell
+cd examples/resource && gradle run
+```
+
+The detected resource attributes would depend on the environment in which the application is run.

examples/resource/build.gradle

@@ -19,18 +19,31 @@ plugins {
 	id 'com.google.cloud.tools.jib'
 }
 
-
 description = 'Examples for showing resource detection in various GCP environments.'
 
 dependencies {
+	implementation(libraries.opentelemetry_api)
+	// Detects resource attributes from various GCP environments
 	implementation(libraries.opentelemetry_gcp_resources)
+	// Provides resources to the autoconfiguration module
 	implementation(libraries.opentelemetry_sdk_autoconf)
-	implementation(libraries.opentelemetry_otlp_exporter)
 }
 
 mainClassName = 'com.google.cloud.opentelemetry.example.resource.ResourceExample'
 
 jib {
 	from.image = 'gcr.io/distroless/java-debian10:11'
 	containerizingMode = 'packaged'
-}
+}
+
+def autoconf_config = [
+	'-Dotel.traces.exporter=none',
+	'-Dotel.metrics.exporter=none',
+	'-Dotel.logs.exporter=none',
+	'-Dotel.java.global-autoconfigure.enabled=true',
+	'-Dotel.service.name=example-resource',
+]
+
+application {
+	applicationDefaultJvmArgs = autoconf_config
+}

examples/resource/src/main/java/com/google/cloud/opentelemetry/example/resource/ResourceExample.java

@@ -16,16 +16,34 @@
 package com.google.cloud.opentelemetry.example.resource;
 
 import io.opentelemetry.contrib.gcp.resource.GCPResourceProvider;
+import io.opentelemetry.sdk.OpenTelemetrySdk;
+import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;
 import io.opentelemetry.sdk.autoconfigure.ResourceConfiguration;
 import io.opentelemetry.sdk.resources.Resource;
+import io.opentelemetry.sdk.trace.SdkTracerProvider;
 
 public class ResourceExample {
   public static void main(String[] args) {
-    System.out.println("Detecting resource: Autoconfigure");
+    // Get the autoconfigured OpenTelemetry SDK
+    OpenTelemetrySdk openTelemetrySdk =
+        AutoConfiguredOpenTelemetrySdk.initialize().getOpenTelemetrySdk();
+
+    // Shows the resource attributes detected from the environment variables
+    // and system properties.
+    System.out.println("Detecting resource: Environment");
     Resource autoResource = ResourceConfiguration.createEnvironmentResource();
-    System.out.println(autoResource.getAttributes());
+    System.out.println(autoResource.getAttributes() + "\n");
+
+    // Shows the resource attributes detected by the GCP Resource Provider
     System.out.println("Detecting resource: hardcoded");
     GCPResourceProvider resourceProvider = new GCPResourceProvider();
-    System.out.println(resourceProvider.getAttributes());
+    System.out.println(resourceProvider.getAttributes() + "\n");
+
+    // Shows the attributes attached to the Resource that was set for TracerProvider
+    // via the autoconfiguration SPI.
+    // This works similarly for MeterProvider and LoggerProvider.
+    System.out.println("Detecting resource: Autoconfigure");
+    SdkTracerProvider autoConfTracerProvider = openTelemetrySdk.getSdkTracerProvider();
+    System.out.println(autoConfTracerProvider.toString() + "\n");
   }
 }