OTEL Event Data

This guide covers the configuration settings for Open Telemetry event onboarding into the Crosswork Assurance 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

Crosswork 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 uses values from the raw OTEL event fields to map to the computed entityId and entityClass values. These rules must be configured via a Crosswork 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 manage 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. 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 Crosswork 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 Crosswork Assurance's Grafana for application-level monitoring.

• Metric: pca_mapping_failure
• Common error_type values:
  • missing_mapping
  • mapping_eval_failure
  • missing_mandatory_field