azuredataexplorerexporter

Azure Data Explorer Exporter

Status
Stability	beta: traces, metrics, logs
Distributions	contrib
Issues
Code Owners	@asaharn, @ag-ramachandran

This exporter sends metrics, logs and trace data to Azure Data Explorer, Azure Synapse Data Explorer and Real time analytics in Fabric

Configuration

The following settings are required:

• cluster_uri (no default): The cluster name of the provisioned ADX cluster to ingest the data.
• application_id (no default): The client id to connect to the cluster and ingest data.
• application_key (no default): The cluster secret corresponding to the client id.
• tenant_id (no default): The tenant id where the application_id is referenced from.

The following settings can be optionally configured and have default values:

Note that the database tables are expected to be created upfront before the exporter is in operation , the definition of these are in the section Database and Table definition scripts

• db_name (default = "oteldb"): The ADX database where the tables are present to ingest the data.

• metrics_table_name (default = OTELMetrics): The target table in the database db_name that stores exported metric data.

• logs_table_name (default = OTELLogs): The target table in the database db_name that stores exported logs data.

• traces_table_name (default = OTELTraces): The target table in the database db_name that stores exported traces data.

  Optionally the following table mappings can be specified if the data needs to be mapped to a different table on ADX. This uses json table mapping that can be used to map attributes to target tables

• metrics_table_json_mapping (optional, no default): The table mapping name to be used for the table db_name.metrics_table_name

• logs_table_json_mapping (optional, no default): The table mapping name to be used for the table db_name.logs_table_name

• traces_table_json_mapping (optional, no default): The table mapping name to be used for the table db_name.traces_table_name

• ingestion_type (possible values=queued / managed, default = queued): ADX ingest can happen in managed streaming or queued modes.

Note: Streaming ingestion has to be enabled on ADX [configure the ADX cluster] in case of streaming option. Refer the query below to check if streaming is enabled

.show database <DB-Name> policy streamingingestion

An example configuration is provided as follows:

exporters:
  azuredataexplorer:
    # Kusto cluster uri
    cluster_uri: "https://CLUSTER.kusto.windows.net"
    # Client Id
    application_id: "f80da32c-108c-415c-a19e-643f461a677a"
    # The client secret for the client
    application_key: "xx-xx-xx-xx"
    # The tenant
    tenant_id: "21ff9e36-fbaa-43c8-98ba-00431ea10bc3"
    # A managed identity id to authenticate with. 
    # Set to "system" for system-assigned managed identity.
    # Set the MI client Id (GUID) for user-assigned managed identity.
    managed_identity_id: "z80da32c-108c-415c-a19e-643f461a677a"
    # Database for the logs
    db_name: "oteldb"
    # Metric table name
    metrics_table_name: "OTELMetrics"
    # Log table name
    logs_table_name: "OTELLogs"
    # Traces table
    traces_table_name: "OTELTraces"
    # Metric table mapping name
    metrics_table_json_mapping: "otelmetrics_mapping"
    # Log table mapping name
    logs_table_json_mapping: "otellogs_mapping"
    # Traces mapping table
    traces_table_json_mapping: "oteltraces_mapping"
    # Type of ingestion managed or queued
    ingestion_type : "managed"
    #other available exporter helper options, see more here: https://github.com/open-telemetry/opentelemetry-collector/blob/main/exporter/exporterhelper/README.md
    # timeout: 10s
    # sending_queue:
    #   enabled: true
    #   num_consumers: 2
    #   queue_size: 10
    # retry_on_failure:
    #   enabled: true
    #   initial_interval: 10s
    #   max_interval: 60s
    #   max_elapsed_time: 10m

Attribute mapping

This exporter maps OpenTelemetry trace, metric and log attributes to specific structures in the ADX tables. These can then be extended by usage of update policies in ADX if needed

Traces

Metrics

Logs

Database and Table definition scripts

The following tables need to be created in the database specified in the configuration.

.create-merge table <Logs-Table-Name> (Timestamp:datetime, ObservedTimestamp:datetime, TraceID:string, SpanID:string, SeverityText:string, SeverityNumber:int, Body:string, ResourceAttributes:dynamic, LogsAttributes:dynamic) 

.create-merge table <Metrics-Table-Name> (Timestamp:datetime, MetricName:string, MetricType:string, MetricUnit:string, MetricDescription:string, MetricValue:real, Host:string, ResourceAttributes:dynamic,MetricAttributes:dynamic) 

.create-merge table <Traces-Table-Name> (TraceID:string, SpanID:string, ParentID:string, SpanName:string, SpanStatus:string, SpanKind:string, StartTime:datetime, EndTime:datetime, ResourceAttributes:dynamic, TraceAttributes:dynamic, Events:dynamic, Links:dynamic) 

// This is an optional column to store the status code and message as a dynamic field. This augments the status field with Status code and status message

.alter-merge table <Traces-Table-Name> (SpanStatusMessage:string) 

//Enable streaming ingestion( for managed streaming) for the created tables using
.alter table <Table-Name> policy streamingingestion enable

Optional configurations/Enhancements suggestions

• Using update policies , the collected data can further be processed as per application need. The following is an example where histogram metrics are exported to a histo specific table (buckets and aggregates)

.create table HistoBucketData (Timestamp: datetime, MetricName: string , MetricType: string , Value: double, LE: double, Host: string , ResourceAttributes: dynamic, MetricAttributes: dynamic )

.create function 
with ( docstring = "Histo bucket processing function", folder = "UpdatePolicyFunctions") ExtractHistoColumns()
{
    OTELMetrics
    | where MetricType == 'Histogram' and MetricName has "_bucket"
    | extend f=parse_json(MetricAttributes)
    | extend le=todouble(f.le)
    | extend M_name=replace_string(MetricName, '_bucket','')
    | project Timestamp, MetricName=M_name, MetricType, MetricValue, LE=le, Host, ResourceAttributes, MetricAttributes
}

.alter table HistoBucketData policy update 
@'[{ "IsEnabled": true, "Source": "OTELMetrics","Query": "ExtractHistoColumns()", "IsTransactional": false, "PropagateIngestionProperties": false}]'

//Below code creates a table which only contains count and sum values of Histogram metric type and attaches an update policy to it

 .create table HistoData (Timestamp: datetime, MetricName: string , MetricType: string , Count: double, Sum: double, Host: string , ResourceAttributes: dynamic, MetricAttributes: dynamic)

 .create function 
with ( docstring = "Histo sum count processing function", folder = "UpdatePolicyFunctions") ExtractHistoCountColumns()
{
   OTELMetrics
    | where MetricType =='Histogram'
    | where MetricName has "_count"
    | extend Count=MetricValue
    | extend M_name=replace_string(MetricName, '_bucket','')
    | join kind=inner (OTELMetrics
    | where MetricType =='Histogram'
    | where MetricName has "_sum"
    | project Sum = MetricValue , Timestamp)
 on Timestamp | project Timestamp, MetricName=M_name, MetricType, Count, Sum, Host, ResourceAttributes, MetricAttributes
}

.alter table HistoData policy update 
@'[{ "IsEnabled": true, "Source": "RawMetricsData","Query": "ExtractHistoCountColumns()", "IsTransactional": false, "PropagateIngestionProperties": false}]'

Opentelemetry Exporter Helper Configurations

The ADX exporter now includes support for Opentelemetry exporter helper configurations. This feature allows you to leverage the exporter helper capabilities(retries, timeout etc.) provided natively by Otel. Read more here.

Please note that this configuration is not enabled by default. To utilize the Opentelemetry exporter helper, you will need to add it manually to the configuration.

Example Configuration

# Example Opentelemetry Exporter Configuration
  timeout: 10s
  sending_queue:
      enabled: true
      num_consumers: 2
      queue_size: 10
  retry_on_failure:
      enabled: true
      initial_interval: 10s
      max_interval: 60s
      max_elapsed_time: 10m