Skip to main content
Applies to BloodHound Enterprise and CE Use optional collection performance telemetry to diagnose and tune OpenHound Okta collection performance. Telemetry is disabled by default and does not change the collection scope, schedule, Okta permissions, or number of Okta requests. When enabled, the collector writes bounded, value-free JSONL diagnostics for endpoint latency, HTTP outcomes, retries, quota observations, concurrency, pacing, pagination, and row counts.

Configure Telemetry

Add the following section to config.toml:
config.toml
Set output_directory outside the raw collection output directory. The collector rejects a nested location so the telemetry file is not treated as collection data or uploaded with it. Run the Okta collection normally. The same configuration applies to interactive, scheduled, and containerized collections. Each collection writes one file named openhound-okta-<opaque-run-id>.jsonl in the configured output directory.

Review Telemetry Records

Each JSONL line is an independently parseable record. The file starts with a run_start record, followed by periodic interval records, and normally ends with a run_summary record. Interrupted or incomplete collections retain records that were flushed before the interruption.

Telemetry Settings

You can set the following values in config.toml or with the equivalent environment variable. Environment variables take precedence over config.toml. Replace {PREFIX} with SOURCES__SOURCE__OKTA__TELEMETRY in the environment variables below.
Parameter NameEnvironment VariableDefaultDescription
enabledfalseEnables telemetry. No telemetry file is created when this is false or omitted.
output_directory./telemetryDirectory for the JSONL file. It must be outside the raw collection output directory.
reporting_interval_seconds60Interval at which the collector flushes aggregated diagnostic records. Must be greater than zero.
max_file_bytes10485760Maximum telemetry file size. Must be at least 65536 bytes.
max_interval_records1440Maximum number of interval records. Must be at least 1.
queue_capacity16Maximum number of records waiting for export. Must be at least 2.
The collector bounds telemetry memory, queue depth, interval records, and file size. If the telemetry destination is unavailable, the exporter fails, or a limit is reached, the collection continues. The diagnostic records indicate dropped records, truncation, or exporter failure; an incomplete telemetry summary does not mean that the Okta collection failed.

Telemetry Metrics

Telemetry separates the following measurements so you can identify where collection time is spent:
MeasurementDescription
http_executionMeasures request execution through response-body transfer. It excludes JSON decoding and downstream DLT row conversion.
slot_waitMeasures time waiting for the Okta endpoint-family concurrency slot and the organization-wide org_concurrency gate.
proactive_pacing_waitMeasures waits caused by pacing against observed quota headers.
retry_backoff_waitMeasures the actual wait before a retry. Retry delay totals are also recorded by retry category.
The summary records the effective DLT extraction settings (extract_workers and extract_max_parallel_items) and the effective Okta performance settings, including page sizes, endpoint concurrency, retry window, and rate-limit reserve. Page and row counts describe data yielded by Okta pagination; they do not confirm that DLT committed the rows to the raw collection.
Telemetry uses normalized endpoint templates and excludes credentials, tenant hostnames, raw URLs, cursors, object identifiers, response bodies, profiles, and exception text.Store the JSONL files as diagnostic artifacts and do not place them under the raw collection directory.