PingOne Advanced Identity Cloud

Manage log event exporters using the API

Learn more about exporting PingOne Advanced Identity Cloud log events in Export log events to an external monitoring tool.

Log event exporter service API endpoints

The log event exporter service provides these Advanced Identity Cloud API endpoints:

  • Telemetry API endpoint (/environment/telemetry)

    • Use GET to view the log event exporter configuration. Note that you can only have one log event exporter in your tenant environment.

  • OTLP telemetry API endpoint (/environment/telemetry/otlp)

    • Use GET to view a specified OTLP log event exporter configuration.

    • Use PUT to create or update an OTLP log event exporter configuration.

    • Use DELETE to delete an OTLP log event exporter configuration.

  • Splunk API endpoint (/environment/telemetry/splunk)

    • Use GET to view a specified Splunk log event exporter configuration.

    • Use PUT to create or update a Splunk log event exporter configuration.

    • Use DELETE to delete a Splunk log event exporter configuration.

Authenticate to log event exporter API endpoints

To authenticate to log event exporter API endpoints, use an access token created with the following scope:

Scope Description

fr:idc:telemetry:*

Full access to log event exporter API endpoints. Use this scope to view, create, update, or delete log event exporters.

View the log event exporter configuration

In your tenant environment:

  1. Get an access token created with the fr:idc:telemetry:* scope.

  2. Get the log event exporter configuration from the /environment/telemetry endpoint:

    $ curl \
--request GET 'https://<tenant-env-fqdn>/environment/telemetry' \(1)
--header 'Authorization: Bearer <access-token>' \(2)
--header 'Content-Type: application/json'
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <access-token> with the access token.

    The response shows the log event exporter configuration:

    Show example response for an OTLP log event exporter 
    {
  "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 event exporter.
    4 The Advanced Identity Cloud log sources that are exported.
    5 The exporter type, either GRPC (for a gRPC-based monitoring tool) or HTTP (for Systems using JSON-based logs).
    Show example response for a Splunk log event exporter 
    {
  "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 event exporter.
    3 The Advanced Identity Cloud log sources that are exported.

Configure an OTLP log event exporter

An Advanced Identity Cloud tenant environment can have only one log event exporter. You must delete the existing exporter before creating a new OTLP log event exporter.

To create or update an OTLP log event exporter configuration, send a PUT request to the /environment/telemetry/otlp endpoint.

In your tenant environment:

  1. Get an access token created with the fr:idc:telemetry:* scope.

  2. Run the following command:

    $ curl \
--request PUT 'https://<tenant-env-fqdn>/environment/telemetry/otlp/<ID>' \(1)(2)
--header 'Authorization: Bearer <access-token>' \(3)
--header 'Content-Type: application/json' \
--data '{
  "basicAuth": { (4)
    "username": "<username>",
    "password": "<password>"
  },
  "encoding": "<encoding-format>", (5)
  "endpoint": "<monitoring-tool-url>", (6)
  "headers": { (7)
      "api-key": "key"
  },
  "sources": [ (8)
    "am-activity",
    "idm-activity"
  ],
  "type": "<exporter-type>" (9)
}'
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <ID> with a unique identifier for your log exporter configuration (for example, mySIEM-otlp).
    3 Replace <access-token> with the access token.
    4 Replace <username> and <password> with the credentials for your external monitoring tool.
    5 Replace <encoding-format> 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 <monitoring-tool-url> 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).
    7 (Optional) Define any headers to apply to all outgoing data (traces, metrics, and logs). Omit this section if not needed.
    8 Specify a comma-separated list of log sources to export to the external monitoring tool.
    9 Replace <exporter-type> with the exporter type, either GRPC (for gRPC-based monitoring tools) or HTTP (for systems using JSON-based logs). Refer to your monitoring tool vendor’s documentation for details.
    Show example configuration body 
    {
  "basicAuth": {
    "username": "admin",
    "password": "x6ghe*suj"
  },
  "encoding": "PROTO",
  "endpoint": "https://example-siem.com:4317",
  "headers": {
      "api-key": "key"
  },
  "sources": [
    "am-activity",
    "idm-activity"
  ],
  "type": "GRPC"
}
    The log event exporter starts exporting events after a few minutes. Even if credentials are rotated during this period, no logs are lost.

Configure a Splunk log event exporter

An Advanced Identity Cloud tenant environment can have only one log event exporter. You must delete the existing exporter before creating a new OTLP log event exporter.

To create or update a Splunk log event exporter configuration, send a PUT request to the /environment/telemetry/splunk endpoint.

In your tenant environment:

  1. Get an access token created with the fr:idc:telemetry:* scope.

  2. Run the following command:

    $ curl \
--request PUT 'https://<tenant-env-fqdn>/environment/telemetry/splunk/<ID>' \(1)(2)
--header 'Authorization: Bearer <access-token>' \(3)
--header 'Content-Type: application/json' \
--data '{
  "endpoint": "<monitoring-tool-url>", (4)
  "token": "<splunk-hec-token>", (5)
  "index": "<splunk-index>", (6)
  "sources": [ (7)
    "am-activity",
    "idm-activity"
  ]
}'
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <ID> with a unique ID for your log exporter configuration, for example mySIEM-splunk.
    3 Replace <access-token> with the access token.
    4 Replace <monitoring-tool-url> with the Splunk destination URL for receiving log events.
    5 Replace <splunk-hec-token> with the HEC token, obtained when you set up HEC for splunk.
    6 (Optional) Replace <index> with the name of the specific Splunk index you want to target. Omit this line if not needed.
    7 Specify a comma-separated list of log sources to export.
    Show example configuration body 
    {
  "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 event exporter starts exporting events after a few minutes. Even if credentials are rotated during this period, no logs are lost.

Delete the log event exporter configuration

You must delete a log event exporter configuration before you can create a new one.

In your tenant environment:

  1. Get an access token created with the fr:idc:telemetry:* scope.

  2. Delete the log event exporter configuration:

    $ curl \
--request DELETE 'https://<tenant-env-fqdn>/environment/telemetry/<ID>' \(1)(2)
--header 'Authorization: Bearer <access-token>' \(3)
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <ID> with the ID of the log exporter configuration.
    3 Replace <access-token> with the access token.