|
| 1 | +# Google Cloud Authentication Extension |
| 2 | + |
| 3 | +The Google Cloud Auth Extension allows the users to export telemetry from their applications to Google Cloud using the built-in OTLP exporters.\ |
| 4 | +The extension takes care of the necessary configuration required to authenticate to GCP to successfully export telemetry. |
| 5 | + |
| 6 | +## Prerequisites |
| 7 | + |
| 8 | +### Ensure the presence of Google Cloud Credentials on your machine/environment |
| 9 | + |
| 10 | +```shell |
| 11 | +gcloud auth application-default login |
| 12 | +``` |
| 13 | + |
| 14 | +Executing this command will save your application credentials to default path which will depend on the type of machine - |
| 15 | + |
| 16 | +- Linux, macOS: `$HOME/.config/gcloud/application_default_credentials.json` |
| 17 | +- Windows: `%APPDATA%\gcloud\application_default_credentials.json` |
| 18 | + |
| 19 | +**NOTE: This method of authentication is not recommended for production environments.** |
| 20 | + |
| 21 | +Next, export the credentials to `GOOGLE_APPLICATION_CREDENTIALS` environment variable - |
| 22 | + |
| 23 | +For Linux & MacOS: |
| 24 | + |
| 25 | +```shell |
| 26 | +export GOOGLE_APPLICATION_CREDENTIALS=$HOME/.config/gcloud/application_default_credentials.json |
| 27 | +``` |
| 28 | + |
| 29 | +These credentials are built-in running in a Google App Engine, Google Cloud Shell or Google Compute Engine environment. |
| 30 | + |
| 31 | +### Configuring the extension |
| 32 | + |
| 33 | +The extension can be configured either by environment variables or system properties. |
| 34 | + |
| 35 | +Here is a list of configurable options for the extension: |
| 36 | + |
| 37 | +- `GOOGLE_CLOUD_PROJECT`: Environment variable that represents the Google Cloud Project ID to which the telemetry needs to be exported. |
| 38 | + - Can also be configured using `google.cloud.project` system property. |
| 39 | + - This is a required option, the agent configuration will fail if this option is not set. |
| 40 | +- `GOOGLE_CLOUD_QUOTA_PROJECT`: Environment variable that represents the Google Cloud Quota Project ID which will be charged for the GCP API usage. To learn more about a *quota project*, see [here](https://cloud.google.com/docs/quotas/quota-project). |
| 41 | + - Can also be configured using `google.cloud.quota.project` system property. |
| 42 | + - If this option is not configured, the extension will use the Quota Project ID found in the Application Default Credentials (ADC), if available. For more information on application default credentials, see [here](https://cloud.google.com/docs/authentication/application-default-credentials). |
| 43 | + |
| 44 | +## Usage |
| 45 | + |
| 46 | +### With OpenTelemetry Java agent |
| 47 | + |
| 48 | +The OpenTelemetry Java Agent Extension can be easily added to any Java application by modifying the startup command to the application. |
| 49 | +For more information on Extensions, see the [documentation here](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/examples/extension/README.md). |
| 50 | + |
| 51 | +Below is a snippet showing how to add the extension to a Java application using the Gradle build system. |
| 52 | + |
| 53 | +```gradle |
| 54 | +// Specify OpenTelemetry Autoinstrumentation Java Agent Path. |
| 55 | +def otelAgentPath = <OpenTelemetry Java Agent location> |
| 56 | +// Specify the path for Google Cloud Authentication Extension for the Java Agent. |
| 57 | +def extensionPath = <Google Cloud Authentication Extension location> |
| 58 | +def googleCloudProjectId = <Your Google Cloud Project ID> |
| 59 | +def googleOtlpEndpoint = <Google Cloud OTLP endpoint> |
| 60 | +
|
| 61 | +val autoconf_config = listOf( |
| 62 | + "-javaagent:${otelAgentPath}", |
| 63 | + "-Dotel.javaagent.extensions=${extensionPath}", |
| 64 | + // Configure the GCP Auth extension using system properties. |
| 65 | + // This can also be configured using environment variables. |
| 66 | + "-Dgoogle.cloud.project=${googleCloudProjectId}", |
| 67 | + // Configure auto instrumentation. |
| 68 | + "-Dotel.exporter.otlp.traces.endpoint=${googleOtlpEndpoint}", |
| 69 | + '-Dotel.java.global-autoconfigure.enabled=true', |
| 70 | + // Optionally enable the built-in GCP resource detector |
| 71 | + '-Dotel.resource.providers.gcp.enabled=true' |
| 72 | + '-Dotel.traces.exporter=otlp', |
| 73 | + '-Dotel.metrics.exporter=logging' |
| 74 | +) |
| 75 | +
|
| 76 | +application { |
| 77 | + ... |
| 78 | + applicationDefaultJvmArgs = autoconf_config |
| 79 | + ... |
| 80 | +} |
| 81 | +``` |
| 82 | + |
| 83 | +### Without OpenTelemetry Java agent |
| 84 | + |
| 85 | +This extension can be used without the OpenTelemetry Java agent by leveraging the [OpenTelemetry SDK Autoconfigure](https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk-extensions/autoconfigure/README.md) module.\ |
| 86 | +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. |
| 87 | + |
| 88 | +Below is a snippet showing how to use this extension as a dependency when the application is not instrumented using the OpenTelemetry Java agent. |
| 89 | + |
| 90 | +```gradle |
| 91 | +dependencies { |
| 92 | + implementation("io.opentelemetry:opentelemetry-api") |
| 93 | + implementation("io.opentelemetry:opentelemetry-sdk") |
| 94 | + implementation("io.opentelemetry:opentelemetry-exporter-otlp") |
| 95 | + implementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure") |
| 96 | + // include the auth extension dependency |
| 97 | + implementation("io.opentelemetry.contrib:opentelemetry-gcp-auth-extension") |
| 98 | +
|
| 99 | + // other dependencies |
| 100 | + ... |
| 101 | +
|
| 102 | +} |
| 103 | +
|
| 104 | +val autoconf_config = listOf( |
| 105 | + '-Dgoogle.cloud.project=your-gcp-project-id', |
| 106 | + '-Dotel.exporter.otlp.endpoint=https://your.otlp.endpoint:1234', |
| 107 | + '-Dotel.traces.exporter=otlp', |
| 108 | + '-Dotel.java.global-autoconfigure.enabled=true' |
| 109 | +
|
| 110 | + // any additional args |
| 111 | + ... |
| 112 | +) |
| 113 | +
|
| 114 | +application { |
| 115 | + applicationDefaultJvmArgs = autoconf_config |
| 116 | +
|
| 117 | + // additional configuration |
| 118 | + ... |
| 119 | +} |
| 120 | +``` |
| 121 | + |
| 122 | +## Component Owners |
| 123 | + |
| 124 | +- [Josh Suereth](https://github.com/jsuereth), Google |
| 125 | +- [Pranav Sharma](https://github.com/psx95), Google |
| 126 | + |
| 127 | +Learn more about component owners in [component_owners.yml](../.github/component_owners.yml). |
0 commit comments