This guide covers the configuration settings for Open Telemetry event onboarding into the PCA Event Explorer.
What must be present for OTEL events to appear correctly
Every OTEL event record must include the following fields:
- timeUnixNano
- eventName or attributes.eventName
- attributes.event_class or attributes.alert_fingerprint
- attributes.data_type
- attributes.startTimestamp
- attributes.state
Provider Connectivity Assurance then computes two fields based on specified mappings that are configured as settings:
- attributes.entityId
- attributes.entityClass
If either computed field cannot be produced, the payload is rejected from the normal ingestion path.
How the otel-mapping computation works
The mapping computation of uses values from the raw OTEL event fields to map to the computed entityId and entityClass values. These rules must be configured via a Provider Connectivity Assurance REST API. You can specify many rules to cover multiple input formats for your otel-mappings.
Computation rules:
- every mapping token must be rooted at resourceLogs.*
- + is the supported concatenation operator in mapping expressions
- all tokens in a rule must resolve successfully or that rule is skipped
- resolved concatenated values are joined with - in output values
Typical expressions used as a mapping value:
- resourceLogs.resource.attributes.host.ip
- resourceLogs.resource.attributes.device.ip
- resourceLogs.resource.attributes.device.vendor + resourceLogs.resource.attributes.system.name
- resourceLogs.resource.attributes.device.vendor + resourceLogs.resource.attributes.subsystem
Creating otel-mapping rules via a REST API
The following REST APIs are used to managing otel-mappings:
- GET /api/v3/otel-mappings : returns the active mapping document for the tenant and seeds defaults if it is missing
- PUT /api/v3/otel-mappings : replaces the full ordered rules[] list, requires the _rev for updates
Like all REST APIs, authentication is required. See Configuring OAuth 2.0 Clients for API Access for details on authentication. otel-mappings APIs require a user with Admin privileges to be accessed.
Example PUT body:
{
"data": {
"_rev": "7-3b2f4d7d2c4a0d8c8c3a2b1d9e8f7c6b",
"rules": [
{
"mapping": {
"entityId": "resourceLogs.resource.attributes.host.ip",
"entityClass": "resourceLogs.resource.attributes.device.vendor + resourceLogs.resource.attributes.system.name"
}
},
{
"mapping": {
"entityId": "resourceLogs.resource.attributes.host.ip",
"entityClass": "resourceLogs.resource.attributes.device.vendor + resourceLogs.resource.attributes.subsystem"
}
}
]
}
}Validation rules:
- rules[] cannot be empty
- every rule must contain both entityId and entityClass
- expressions must be rooted at resourceLogs.*
- empty tokens are invalid
Default otel-mappings
The service currently seeds this set of default rules when none are provided:
{
"rules": [
{
"mapping": {
"entityId": "resourceLogs.resource.attributes.device.ip",
"entityClass": "resourceLogs.resource.attributes.device.vendor + resourceLogs.resource.attributes.subsystem"
}
},
{
"mapping": {
"entityId": "resourceLogs.resource.attributes.device.ip",
"entityClass": "resourceLogs.resource.attributes.device.vendor + resourceLogs.resource.attributes.system.name"
}
},
{
"mapping": {
"entityId": "resourceLogs.resource.attributes.host.ip",
"entityClass": "resourceLogs.resource.attributes.device.vendor + resourceLogs.resource.attributes.subsystem"
}
},
{
"mapping": {
"entityId": "resourceLogs.resource.attributes.host.ip",
"entityClass": "resourceLogs.resource.attributes.device.vendor + resourceLogs.resource.attributes.system.name"
}
}
]
}Advanced Troubleshooting
If events do not appear in Event Explorer they are output to a dead letter queue in Provider Connectivity Assurance’s internal Kafka instance. The dead letter queue topic is named following the format otel-<tenantId>-dead-letter-queue .
Additionally, any OTEL events that are received but unable to be mapped will increment a metric in Provider Connectivity Assurance’s Grafana for application level monitoring.
- metric: pca_mapping_failure
- common error_type values:
- missing_mapping
- mapping_eval_failure
- missing_mandatory_field