--- title: Manage log streaming using the API description: Learn more about streaming PingOne Advanced Identity Cloud log events in Stream logs to an external monitoring tool. component: pingoneaic page_id: pingoneaic:tenants:audit-debug-logs-push-api canonical_url: https://docs.pingidentity.com/pingoneaic/tenants/audit-debug-logs-push-api.html keywords: ["Monitoring", "Tenants", "Troubleshooting"] page_aliases: ["release-notes:rapid-channel/audit-debug-logs-push-api.adoc"] section_ids: log-streaming-api-endpoints: Log-streaming service API endpoints authenticate-to-log-event-streaming-api-endpoints: Authenticate to log-streaming service API endpoints log-event-view-streaming-api: View the log-streaming service configuration create-otlp-api: Configure an OTLP log-streaming service example_otlp_log_streaming_service_configuration_requests: Example OTLP log-streaming service configuration requests create-splunk-streaming-api: Configure a Splunk log-streaming service delete-log-streaming-api: Delete the log-streaming service configuration --- # Manage log streaming using the API Learn more about streaming PingOne Advanced Identity Cloud log events in [Stream logs to an external monitoring tool](audit-debug-logs-push.html). ## Log-streaming service API endpoints The log-streaming service provides these Advanced Identity Cloud API endpoints: * [Telemetry](https://docs.pingidentity.com/pingoneaic/_attachments/api/#tag/Telemetry) API endpoint (`/environment/telemetry`) * Use `GET` to view the log-streaming service configuration. Note that you can only have one log-streaming service configuration in your tenant environment. * [OTLP telemetry](https://docs.pingidentity.com/pingoneaic/_attachments/api/#tag/Telemetry/operation/getOTLPExporter) API endpoint (`/environment/telemetry/otlp`) * Use `GET` to view a specified OTLP log-streaming service configuration. * Use `PUT` to create or update an OTLP log-streaming service configuration. * Use `DELETE` to delete an OTLP log-streaming service configuration. * [Splunk telemetry](https://docs.pingidentity.com/pingoneaic/_attachments/api/#tag/Telemetry/operation/getSplunkExporter) API endpoint (`/environment/telemetry/splunk`) * Use `GET` to view a specified Splunk log-streaming service configuration. * Use `PUT` to create or update a Splunk log-streaming service configuration. * Use `DELETE` to delete a Splunk log-streaming service configuration. ## Authenticate to log-streaming service API endpoints To authenticate to log-streaming service API endpoints, use an [access token](../developer-docs/authenticate-to-rest-api-with-access-token.html) created with the following scope: | Scope | Description | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `fr:idc:telemetry:*` | Full access to log-streaming service API endpoints. Use this scope to view, create, update, or delete log-streaming services. | ## View the log-streaming service configuration In your tenant environment: 1. [Get an access token](../developer-docs/authenticate-to-rest-api-with-access-token.html#get_an_access_token) created with the `fr:idc:telemetry:*` scope. 2. Get the log-streaming service configuration from the `/environment/telemetry` endpoint: ```bash $ curl \ --request GET 'https:///environment/telemetry' \(1) --header 'Authorization: Bearer ' \(2) --header 'Content-Type: application/json' ``` | | | | ----- | -------------------------------------------------------------------- | | **1** | Replace \ with the FQDN of your tenant environment. | | **2** | Replace \ with the access token. | The response shows the log-streaming service configuration: > **Collapse: Show example response for an OTLP log-streaming service** > > ```json > { > "otlp": [ > { > "encoding": "PROTO", (1) > "endpoint": "https://example-siem.com:4317", (2) > "id": "mySIEM-otlp", (3) > "sources": [ (4) > "am-everything", > "idm-everything" > ], > "type": "GRPC" (5) > } > ], > "splunk": [] > } > ``` > > | | | > | ----- | -------------------------------------------------------------------------------------------------------------------- | > | **1** | The encoding format for telemetry data, either `PROTO` (Protocol Buffers, the default) or `JSON`. | > | **2** | The destination URL for sending log event data. | > | **3** | A unique identifier for the log-streaming service. | > | **4** | The Advanced Identity Cloud [log sources](audit-debug-log-sources.html) that are streamed. | > | **5** | The streaming service protocol: `GRPC` for a gRPC-based monitoring tool or `HTTP` for Systems using JSON-based logs. | > **Collapse: Show example response for a Splunk log-streaming service** > > ```json > { > "otlp": [], > "splunk": [ > { > "endpoint": "https://splunk:8088/services/collector/event", (1) > "id": "mySIEM-splunk", (2) > "sources": [ (3) > "am-everything", > "idm-everything" > ] > } > ] > } > ``` > > | | | > | ----- | -------------------------------------------------------------------------------------- | > | **1** | The destination URL for sending log event data. | > | **2** | A unique identifier for the log-streaming service. | > | **3** | The Advanced Identity Cloud [sources](audit-debug-log-sources.html) that are streamed. | ## Configure an OTLP log-streaming service | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | An Advanced Identity Cloud tenant environment can have only one log-streaming service configuration. You must delete the existing log-streaming service configuration before creating a new one. | To create or update an OTLP log-streaming service, send a `PUT` request to the `/environment/telemetry/otlp` endpoint. In your tenant environment: 1. [Get an access token](../developer-docs/authenticate-to-rest-api-with-access-token.html#get_an_access_token) created with the `fr:idc:telemetry:*` scope. 2. Run the following command: ```bash $ curl \ --request PUT 'https:///environment/telemetry/otlp/' \(1)(2) --header 'Authorization: Bearer ' \(3) --header 'Content-Type: application/json' \ --data '{ "basicAuth": { (4) "username": "", "password": "" }, "encoding": "", (5) "endpoint": "", (6) "headers": { (7) "api-key": "key" }, "sources": [ (8) "am-activity", "idm-activity" ], "type": "" (9) }' ``` | | | | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **1** | Replace \ with the FQDN of your tenant environment. | | **2** | Replace \ with a unique identifier for your log-streaming service configuration (for example, `mySIEM-otlp`). | | **3** | Replace \ with the access token. | | **4** | Replace \ and \ with the credentials for your external monitoring tool. | | **5** | Replace \ with the encoding format for telemetry data, either `PROTO` (Protocol Buffers, the default) or `JSON`. Refer to your monitoring tool vendor's documentation for details. | | **6** | Replace \ with the destination URL for sending log event data.- For gRPC, this is the host and port (for example, `https://example-siem.com:4317`). - For HTTP, this is the full URL including the path (for example, `https://example-siem.com:4318/v1/logs`).Note that the port can vary depending on your monitoring tool. For example, Grafana Cloud uses the standard HTTPS port `443`. | | **7** | (Optional) Define any headers to apply to all outgoing data (traces, metrics, and logs). Omit this section if not needed. | | **8** | Specify the [log sources](audit-debug-log-sources.html) to stream as a JSON array of strings. | | **9** | The streaming service protocol: `GRPC` for a gRPC-based monitoring tool or `HTTP` for Systems using JSON-based logs. Refer to your monitoring tool vendor's documentation for details. | > **Collapse: Show example configuration body** > > ```json > { > "basicAuth": { > "username": "admin", > "password": "x6ghe*suj" > }, > "encoding": "PROTO", > "endpoint": "https://example-siem.com:4317", > "headers": { > "api-key": "key" > }, > "sources": [ > "am-activity", > "idm-activity" > ], > "type": "HTTP" > } > ``` | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------- | | | The log-streaming service starts streaming events after a few minutes. Even if credentials are rotated during this period, no logs are lost. | ### Example OTLP log-streaming service configuration requests Learn more about configuring Grafana, Datadog, and New Relic in [Set up a log-streaming service](audit-debug-logs-push.html#set-up-log-streaming). > **Collapse: Grafana example configuration request** > > ```bash > $ curl \ > --request PUT 'https:///environment/telemetry/otlp/0' \ > --header 'Authorization: Bearer ' \ > --header 'Content-Type: application/json' \ > --data '{ > "basicAuth": { > "username": "1134238", > "password": "glc_eyJcvIjoiMTMxNDI1JrIjoicDlnMjloRWZ2NzE3SXR5WEFssaN3E3TTEzIiwibSI6eyJyIdjoicHJvZC11csy13ZXNs0LTAifX0=" > }, > "encoding": "PROTO", > "endpoint": "https://otlp-gateway-example.grafana.net/v1/logs", > "sources": [ > "am-activity", > "idm-activity" > ], > "type": "HTTP" > }' > ``` > **Collapse: Datadog example configuration request** > > ```bash > $ curl \ > --request PUT 'https:///environment/telemetry/otlp/datadog' \ > --header 'Authorization: Bearer ' \ > --header 'Content-Type: application/json' \ > --data '{ > "headers": { > "dd-api-key": "" > }, > "encoding": "PROTO", > "endpoint": "https://http-intake.logs.datadoghq.com/v1/logs", > "sources": [ > "am-activity", > "idm-activity" > ], > "type": "HTTP" > }' > ``` > > Learn more about the Datadog endpoint in the [Datadog documentation](https://docs.datadoghq.com/opentelemetry/setup/agentless/logs/?tab=java). > **Collapse: New Relic example configuration request** > > ```bash > $ curl \ > --request PUT 'https:///environment/telemetry/otlp/newrelic' \ > --header 'Authorization: Bearer ' \ > --header 'Content-Type: application/json' \ > --data '{ > "headers": { > "api-key": "" > }, > "encoding": "PROTO", > "endpoint": "https://otlp.example.net/v1/logs", > "sources": [ > "am-activity", > "idm-activity" > ], > "type": "HTTP" > }' > ``` > > Learn more about the New Relic endpoint in the [New Relic documentation](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/). ## Configure a Splunk log-streaming service | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | An Advanced Identity Cloud tenant environment can have only one log-streaming service configuration. You must delete the existing log-streaming service configuration before creating a new one. | To create or update a Splunk log-streaming service configuration, send a `PUT` request to the `/environment/telemetry/splunk` endpoint. In your tenant environment: 1. [Get an access token](../developer-docs/authenticate-to-rest-api-with-access-token.html#get_an_access_token) created with the `fr:idc:telemetry:*` scope. 2. Run the following command: ```bash $ curl \ --request PUT 'https:///environment/telemetry/splunk/' \(1)(2) --header 'Authorization: Bearer ' \(3) --header 'Content-Type: application/json' \ --data '{ "endpoint": "", (4) "token": "", (5) "index": "", (6) "sources": [ (7) "am-activity", "idm-activity" ] }' ``` | | | | ----- | ------------------------------------------------------------------------------------------------------------------------ | | **1** | Replace \ with the FQDN of your tenant environment. | | **2** | Replace \ with a unique ID for your log-streaming service configuration, for example `mySIEM-splunk`. | | **3** | Replace \ with the access token. | | **4** | Replace \ with the Splunk destination URL for receiving log events. | | **5** | Replace \ with the HEC token, obtained when you set up HEC for Splunk. | | **6** | (Optional) Replace \ with the name of the specific Splunk index you want to target. Omit this line if not needed. | | **7** | Specify the [log sources](audit-debug-log-sources.html) to stream as a JSON array of strings. | > **Collapse: Show example configuration body** > > ```json > { > "endpoint": "https://splunk.example.com:8088/services/collector/event", > "token": "12345678-90ab-cdef-1234-567890abcdef", > "index": "log-index", > "sources": [ > "am-activity", > "idm-activity" > ] > } > ``` | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------- | | | The log-streaming service starts streaming events after a few minutes. Even if credentials are rotated during this period, no logs are lost. | ## Delete the log-streaming service configuration You must delete a log-streaming service configuration before you can create a new one. In your tenant environment: 1. [Get an access token](../developer-docs/authenticate-to-rest-api-with-access-token.html#get_an_access_token) created with the `fr:idc:telemetry:*` scope. 2. Delete the log-streaming service configuration: ```bash $ curl \ --request DELETE 'https:///environment/telemetry//' \(1)(2)(3) --header 'Authorization: Bearer ' \(4) ``` | | | | ----- | ----------------------------------------------------------------------------------- | | **1** | Replace \ with the FQDN of your tenant environment. | | **2** | Replace \ with the telemetry format, either `otlp` or `splunk`. | | **3** | Replace \ with the ID of the log-streaming service configuration. | | **4** | Replace \ with the access token. |