Google Cloud Authentication Extension

The Google Cloud Auth Extension allows users to export telemetry from their applications to Google Cloud using the built-in OTLP exporters. The extension takes care of the configuration required to authenticate to GCP successfully.

Prerequisites

Ensure the presence of Google Cloud Credentials on your machine/environment

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:

export GOOGLE_APPLICATION_CREDENTIALS=$HOME/.config/gcloud/application_default_credentials.json

These credentials are built-in running in a Google App Engine, Google Cloud Shell or Google Compute Engine environment.

Configuring the extension

The extension can be configured either by environment variables or system properties.

Here is a list of required and optional configuration available for the extension:

Optional Config

• GOOGLE_CLOUD_PROJECT: Environment variable that represents the Google Cloud Project ID to which the telemetry needs to be exported.

  • Can also be configured using google.cloud.project system property.
  • If neither of these options are set, the extension will attempt to infer the project id from the current credentials as a fallback. Not all credential implementations can provide a project id, so this inference is only a best-effort attempt.
  • Important Note: The agent configuration will fail if this option is not set and cannot be inferred.

• GOOGLE_CLOUD_QUOTA_PROJECT: Environment variable that represents the Google Cloud Quota Project ID that will be charged for the GCP API usage. To learn more about a quota project, see the Quota project overview page. Additional details about configuring the quota project can be found on the Set the quota project page.

  • Can also be configured using google.cloud.quota.project system property.

• GOOGLE_OTEL_AUTH_TARGET_SIGNALS: Environment variable that specifies a comma-separated list of OpenTelemetry signals for which this authentication extension should be active. Valid values are metrics, traces, all, and none. If left unspecified, all is assumed, meaning the extension will attempt to apply authentication to exports for all signals. If none is set, disables authentication for all exports. If set alongside other signal types, it takes precedence and all other signal types will be ignored.

  • Can also be configured using google.otel.auth.target.signals system property.

• GOOGLE_AUTH_TOKEN_TYPE: Environment variable that specifies the type of token that the extension attaches to the exported telemetry. Valid values are access_token and id_token:

  • access_token (default): OAuth 2.0 access token retrieved from the Application Default Credentials. Use this to export telemetry to Google Cloud APIs, for example telemetry.googleapis.com.
  • id_token: Google-signed OpenID Connect ID token minted from the Application Default Credentials for the configured audience. Use this to export telemetry to OTLP endpoints protected by Google IAM-based authentication - for example, an OpenTelemetry Collector running on Cloud Run or behind Identity-Aware Proxy. The Application Default Credentials must be able to mint ID tokens. This is the case for service account based credentials - for example, the default service account of a GCP compute environment, a service account key, or impersonated credentials. When id_token is used, the GOOGLE_CLOUD_PROJECT option is not required and the gcp.project_id resource attribute is not added.
  • Can also be configured using google.auth.token.type system property.

  The value names are consistent with the token_type option of the Google Client Auth Extension for the OpenTelemetry Collector.

• GOOGLE_AUTH_ID_TOKEN_AUDIENCE: Environment variable that specifies the audience used when minting Google-signed ID tokens. Required when GOOGLE_AUTH_TOKEN_TYPE is set to id_token, ignored otherwise. For Cloud Run, this is the URL of the receiving service or one of its custom audiences. For Identity-Aware Proxy, this is the OAuth 2.0 client ID.

  • Can also be configured using google.auth.id.token.audience system property.

Usage

With OpenTelemetry Java agent

The OpenTelemetry Java Agent Extension can be easily added to any Java application by modifying the application's startup command. For more information on Extensions, see the documentation here.

Below is a snippet showing how to add the extension to a Java application using the Gradle build system.

// Specify OpenTelemetry Autoinstrumentation Java Agent Path.
def otelAgentPath = <OpenTelemetry Java Agent location>
// Specify the path for Google Cloud Authentication Extension for the Java Agent.
def extensionPath = <Google Cloud Authentication Extension location>
def googleCloudProjectId = <Your Google Cloud Project ID>
def googleOtlpEndpoint = <Google Cloud OTLP endpoint>

val autoconf_config = listOf(
  "-javaagent:${otelAgentPath}",
  "-Dotel.javaagent.extensions=${extensionPath}",
  // Configure the GCP Auth extension using system properties.
  // This can also be configured using environment variables.
  "-Dgoogle.cloud.project=${googleCloudProjectId}",
  // Configure auto instrumentation.
  "-Dotel.exporter.otlp.traces.endpoint=${googleOtlpEndpoint}",
  '-Dotel.java.global-autoconfigure.enabled=true',
  // Optionally enable the built-in GCP resource detector
  '-Dotel.resource.providers.gcp.enabled=true'
  '-Dotel.traces.exporter=otlp',
  '-Dotel.metrics.exporter=logging'
)

application {
  ...
  applicationDefaultJvmArgs = autoconf_config
  ...
}

Downloading Shaded JAR

You can download the shaded JAR for Google Cloud Authentication Extension from the following link -

https://repo1.maven.org/maven2/io/opentelemetry/contrib/opentelemetry-gcp-auth-extension/<VERSION>/opentelemetry-gcp-auth-extension-<VERSION>-shadow.jar

Replace <VERSION> with the version you wish to download. For instance, shaded variant for v1.44.0-alpha, will be found at -

https://repo1.maven.org/maven2/io/opentelemetry/contrib/opentelemetry-gcp-auth-extension/1.44.0-alpha/opentelemetry-gcp-auth-extension-1.44.0-alpha-shadow.jar

Note: Typically, you would want to use the most recent version of the extension.

Without OpenTelemetry Java agent

This extension can be used without the OpenTelemetry Java agent by leveraging the OpenTelemetry SDK Autoconfigure module. When using the autoconfigured SDK, simply adding this extension as a dependency automatically configures authentication headers and resource attributes for spans, enabling export to Google Cloud.

Below is a snippet showing how to use this extension as a dependency when the application is not instrumented using the OpenTelemetry Java agent.

dependencies {
    implementation("io.opentelemetry:opentelemetry-api")
    implementation("io.opentelemetry:opentelemetry-sdk")
    implementation("io.opentelemetry:opentelemetry-exporter-otlp")
    implementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure")
    // include the auth extension dependency
    implementation("io.opentelemetry.contrib:opentelemetry-gcp-auth-extension")

    // other dependencies
    ...

}

val autoconf_config = listOf(
  '-Dgoogle.cloud.project=your-gcp-project-id',
  '-Dotel.exporter.otlp.endpoint=https://your.otlp.endpoint:1234',
  '-Dotel.traces.exporter=otlp',
  '-Dotel.java.global-autoconfigure.enabled=true'

  // any additional args
  ...
)

application {
  applicationDefaultJvmArgs = autoconf_config

  // additional configuration
  ...
}

Component Owners

• Josh Suereth, Google
• Pranav Sharma, Google

Learn more about component owners in component_owners.yml.