[FDS-2525] Authenticated export of telemetry data

README.md

@@ -33,17 +33,20 @@
     - [3. Start the virtual environment](#3-start-the-virtual-environment)
     - [4. Install `schematic` dependencies](#4-install-schematic-dependencies)
     - [5. Set up configuration files](#5-set-up-configuration-files)
-    - [6. Obtain Google credential files](#6-obtain-google-credential-files)
+    - [6. Obtain Google credential files](#6-obtain-google-credential-files-1)
     - [7. Set up pre-commit hooks](#7-set-up-pre-commit-hooks)
     - [8. Verify your setup](#8-verify-your-setup)
 - [Command Line Usage](#command-line-usage)
 - [Docker Usage](#docker-usage)
-  - [Running the REST API](#running-the-rest-api)
-    - [Example 1: Using the `config.yml` path](#example-1-using-the-configyml-path)
-    - [Example 2: Use environment variables](#example-2-use-environment-variables)
-  - [Running `schematic` to Validate Manifests](#running-schematic-to-validate-manifests)
-    - [Example for macOS/Linux](#example-for-macoslinux)
-    - [Example for Windows](#example-for-windows)
+    - [Running the REST API](#running-the-rest-api)
+      - [Example 1: Using the `config.yml` path](#example-1-using-the-configyml-path)
+      - [Example 2: Use environment variables](#example-2-use-environment-variables)
+    - [Running `schematic` to Validate Manifests](#running-schematic-to-validate-manifests)
+      - [Example for macOS/Linux](#example-for-macoslinux)
+      - [Example for Windows](#example-for-windows)
+- [Exporting OpenTelemetry data from schematic](#exporting-opentelemetry-data-from-schematic)
+  - [Exporting OpenTelemetry data for SageBionetworks employees](#exporting-opentelemetry-data-for-sagebionetworks-employees)
+    - [Exporting data locally](#exporting-data-locally)
 - [Contributors](#contributors)
 
 
@@ -487,6 +490,67 @@ docker run -v %cd%:/schematic \
   -c config.yml validate -mp tests/data/mock_manifests/inValid_Test_Manifest.csv -dt MockComponent -js /schematic/data/example.model.jsonld
 ```
 
+# Exporting OpenTelemetry data from schematic
+This section is geared towards the SageBionetworks specific deployment of schematic as
+an API server running in the Sage specific AWS account.
+
+
+Schematic is setup to produce and export OpenTelemetry data while requests are flowing
+through the application code. This may be accomplished by setting a few environment
+variables wherever the application is running. Those variables are:
+
+- `TRACING_EXPORT_FORMAT`: Determines in what format traces will be exported. Supported values: [`otlp`].
+- `LOGGING_EXPORT_FORMAT`: Determines in what format logs will be exported. Supported values: [`otlp`].
+- `TRACING_SERVICE_NAME`: The name of the service to attach for all exported traces.
+- `LOGGING_SERVICE_NAME`: The name of the service to attach for all exported logs.
+- `DEPLOYMENT_ENVIRONMENT`: The name of the environment to attach for all exported telemetry data.
+- `OTEL_EXPORTER_OTLP_ENDPOINT`: The endpoint to export telemetry data to.
+
+Authentication (Oauth2 client credential exchange):
+
+Used in cases where an intermediate opentelemetry collector is not, or can not be used.
+This option is not preferred over using an intermediate opentelemetry collector, but is 
+left in the code to show how we may export telemetry data with an authorization header 
+deried from an oauth2 client credential exchange flow.
+
+- `TELEMETRY_EXPORTER_CLIENT_ID`: The ID of the client to use when executing the OAuth2.0 "Client Credentials" flow.
+- `TELEMETRY_EXPORTER_CLIENT_SECRET`: The Secret of the client to use when executing the OAuth2.0 "Client Credentials" flow.
+- `TELEMETRY_EXPORTER_CLIENT_TOKEN_ENDPOINT`: The Token endpoint to use when executing the OAuth2.0 "Client Credentials" flow.
+- `TELEMETRY_EXPORTER_CLIENT_AUDIENCE`: The ID of the API server to use when executing the OAuth2.0 "Client Credentials" flow.
+
+Authentication (Static Bearer token)
+
+- `OTEL_EXPORTER_OTLP_HEADERS`: Used for developers to set a static Bearer token to be used when exporting telemetry data.
+
+The above configuration will work when the application is running locally, in a
+container, running in AWS, or running via CLI. The important part is that the
+environment variables are set before the code executes, as the configuration is setup
+when the code runs.
+
+## Exporting OpenTelemetry data for SageBionetworks employees
+The DPE (Data Processing & Engineering) team is responsible for maintaining and giving
+out the above sensitive information. Please reach out to the DPE team if a new ID/Secret
+is needed in order to export telemetry data in a new environment, or locally during
+development.
+
+### Exporting data locally
+In order to conserve the number of monthly token requests that can be made the following
+process should be followed instead of setting the `TELEMETRY_EXPORTER_CLIENT_*`
+environment variables above.
+
+1) Request access to a unique client ID/Secret that identifies you from DPE.
+2) Retrieve a token that must be refreshed every 24 hours via cURL. The specific values will be given when the token is requested. Example:
+```
+curl --request POST \
+  --url https://TOKEN_URL.us.auth0.com/oauth/token \
+  --header 'content-type: application/json' \
+  --data '{"client_id":"...","client_secret":"...","audience":"...","grant_type":"client_credentials"}'
+```
+3) Set an environment variable in your `.env` file like: `OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer ey...`
+
+If you fail to create a new access token after 24 hours you will see HTTP 403 JWT 
+Expired messages when the application attempts to export telemetry data.
+
 # Contributors
 
 Main contributors and developers:

env.example

@@ -13,6 +13,15 @@ SERVICE_ACCOUNT_CREDS='Provide service account creds'
 # LOGGING_SERVICE_NAME=schematic-api
 ## Other examples: dev, staging, prod
 # DEPLOYMENT_ENVIRONMENT=local
+# OTEL_EXPORTER_OTLP_ENDPOINT=https://..../telemetry
+## Opentelemetry authentication
+# TELEMETRY_EXPORTER_CLIENT_ID=...
+# TELEMETRY_EXPORTER_CLIENT_SECRET-...
+# TELEMETRY_EXPORTER_CLIENT_TOKEN_ENDPOINT=...
+# TELEMETRY_EXPORTER_CLIENT_AUDIENCE=...
+## Alternative Opentelemetry authentication: Sets a static Authorization header to use for all requests. Used when developing locally
+# OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer ey...
+
 
 # Used during integration test run to determine if files will be output for manual
 # inspection. These tests cannot fully finish all validation via code. All of these