Condividi tramite

Configurare i client OpenTelemetry (OTLP) per l'invio di dati a Unity Catalog

Importante

Questa funzionalità è in versione beta.

Zerobus Ingest include un endpoint OTLP (OpenTelemetry Protocol). È possibile eseguire il push di tracce, log e metriche direttamente nelle tabelle Delta del catalogo Unity usando gli SDK e gli agenti di raccolta OpenTelemetry standard, senza librerie personalizzate. Questa pagina illustra il recupero dell'endpoint, la creazione di tabelle di destinazione, la configurazione di un'entità servizio e l'invio dei primi dati di telemetria.

Ottieni l'endpoint di inserimento Zerobus e l'URL dell'area di lavoro

L'URL dell'endpoint segue questo modello:

  • URL area di lavoro: https://<databricks-instance>.azuredatabricks.net
  • Endpoint server: <workspace-id>.zerobus.<region>.azuredatabricks.net

Per esempio:

  • URL area di lavoro: https://adb-1234567890123456.12.azuredatabricks.net
  • Endpoint server: 1234567890123456.zerobus.eastus.azuredatabricks.net

Per ulteriori dettagli sulla ricerca dell'ID dell'area di lavoro, dell'URL e della regione, vedere Ottenere l'URL dell'area di lavoro e l'endpoint di inserimento Zerobus.

Creare Tabelle di Destinazione nel Unity Catalog

È necessario creare le tabelle Delta di destinazione prima di inviare i dati. Ogni tipo di segnale (tracce, log, metriche) richiede una propria tabella con uno schema specifico.

Prerequisiti:

  • DBR 15.3 o superiore: è obbligatorio per eseguire query sui dati di tipo VARIANT.
  • (Facoltativo) DBR 17.2 o versione successiva: richiesto per il supporto alla suddivisione delle varianti, che migliora le prestazioni delle query. Per altre informazioni, vedere Ottimizzare le prestazioni sui dati VARIANT con shredding

Per configurare le tabelle:

  1. Sostituire <catalog>.<schema>.<prefix> con il catalogo, lo schema e il prefisso del nome di tabella desiderato.
  2. Sostituire <service-principal-uuid> con l'ID app (UUID) del principale del servizio. Per trovarlo, passa alla scheda Configurazioni del principale del servizio nella tua area di lavoro Databricks.
  3. Esegui lo script in Databricks SQL.

Tabella degli span

La tabella degli intervalli archivia i dati di traccia distribuiti, inclusi tempo di esecuzione, stato e attributi per ogni intervallo.

CREATE TABLE <catalog>.<schema>.<prefix>_otel_spans (
  record_id STRING,
  time TIMESTAMP,
  date DATE,
  service_name STRING,
  trace_id STRING,
  span_id STRING,
  trace_state STRING,
  parent_span_id STRING,
  flags INT,
  name STRING,
  kind STRING,
  start_time_unix_nano LONG,
  end_time_unix_nano LONG,
  attributes VARIANT,
  dropped_attributes_count INT,
  events ARRAY<STRUCT<
    time_unix_nano: LONG,
    name: STRING,
    attributes: VARIANT,
    dropped_attributes_count: INT
  >>,
  dropped_events_count INT,
  links ARRAY<STRUCT<
    trace_id: STRING,
    span_id: STRING,
    trace_state: STRING,
    attributes: VARIANT,
    dropped_attributes_count: INT,
    flags: INT
  >>,
  dropped_links_count INT,
  status STRUCT<
    message: STRING,
    code: STRING
  >,
  resource STRUCT<
    attributes: VARIANT,
    dropped_attributes_count: INT
  >,
  resource_schema_url STRING,
  instrumentation_scope STRUCT<
    name: STRING,
    version: STRING,
    attributes: VARIANT,
    dropped_attributes_count: INT
  >,
  span_schema_url STRING
) USING DELTA
CLUSTER BY (time, service_name, trace_id)
TBLPROPERTIES (
  'otel.schemaVersion' = 'v2',
  'delta.checkpointPolicy' = 'classic',
  'delta.enableVariantShredding' = 'true', -- optional
  'delta.feature.variantShredding-preview' = 'supported', -- optional
  'delta.feature.variantType-preview' = 'supported' -- optional
);

Tabella Dati Registrati

La tabella logs archivia i record di log strutturati, inclusi livello di gravità, contenuto e attributi delle risorse.

CREATE TABLE <catalog>.<schema>.<prefix>_otel_logs (
  record_id STRING,
  time TIMESTAMP,
  date DATE,
  service_name STRING,
  event_name STRING,
  trace_id STRING,
  span_id STRING,
  time_unix_nano LONG,
  observed_time_unix_nano LONG,
  severity_number STRING,
  severity_text STRING,
  body VARIANT,
  attributes VARIANT,
  dropped_attributes_count INT,
  flags INT,
  resource STRUCT<
    attributes: VARIANT,
    dropped_attributes_count: INT
  >,
  resource_schema_url STRING,
  instrumentation_scope STRUCT<
    name: STRING,
    version: STRING,
    attributes: VARIANT,
    dropped_attributes_count: INT
  >,
  log_schema_url STRING
) USING DELTA
CLUSTER BY (time, service_name)
TBLPROPERTIES (
  'otel.schemaVersion' = 'v2',
  'delta.checkpointPolicy' = 'classic',
  'delta.enableVariantShredding' = 'true', -- optional
  'delta.feature.variantShredding-preview' = 'supported', -- optional
  'delta.feature.variantType-preview' = 'supported' -- optional
);

Tabella delle metriche

La tabella delle metriche archivia le misurazioni dell'indicatore, della somma e dell'istogramma insieme agli attributi associati all'ambito di risorsa e di strumentazione.

CREATE TABLE <catalog>.<schema>.<prefix>_otel_metrics (
  record_id STRING,
  time TIMESTAMP,
  date DATE,
  service_name STRING,
  start_time_unix_nano LONG,
  time_unix_nano LONG,
  name STRING,
  description STRING,
  unit STRING,
  metric_type STRING,
  gauge STRUCT<
    value: DOUBLE,
    exemplars: ARRAY<STRUCT<
      time_unix_nano: LONG,
      value: DOUBLE,
      span_id: STRING,
      trace_id: STRING,
      filtered_attributes: VARIANT
    >>,
    attributes: VARIANT,
    flags: INT
  >,
  sum STRUCT<
    value: DOUBLE,
    exemplars: ARRAY<STRUCT<
      time_unix_nano: LONG,
      value: DOUBLE,
      span_id: STRING,
      trace_id: STRING,
      filtered_attributes: VARIANT
    >>,
    attributes: VARIANT,
    flags: INT,
    aggregation_temporality: STRING,
    is_monotonic: BOOLEAN
  >,
  histogram STRUCT<
    count: LONG,
    sum: DOUBLE,
    bucket_counts: ARRAY<LONG>,
    explicit_bounds: ARRAY<DOUBLE>,
    exemplars: ARRAY<STRUCT<
      time_unix_nano: LONG,
      value: DOUBLE,
      span_id: STRING,
      trace_id: STRING,
      filtered_attributes: VARIANT
    >>,
    attributes: VARIANT,
    flags: INT,
    min: DOUBLE,
    max: DOUBLE,
    aggregation_temporality: STRING
  >,
  exponential_histogram STRUCT<
    attributes: VARIANT,
    count: LONG,
    sum: DOUBLE,
    scale: INT,
    zero_count: LONG,
    positive_bucket: STRUCT<
      offset: INT,
      bucket_counts: ARRAY<LONG>
    >,
    negative_bucket: STRUCT<
      offset: INT,
      bucket_counts: ARRAY<LONG>
    >,
    flags: INT,
    exemplars: ARRAY<STRUCT<
      time_unix_nano: LONG,
      value: DOUBLE,
      span_id: STRING,
      trace_id: STRING,
      filtered_attributes: VARIANT
    >>,
    min: DOUBLE,
    max: DOUBLE,
    zero_threshold: DOUBLE,
    aggregation_temporality: STRING
  >,
  summary STRUCT<
    count: LONG,
    sum: DOUBLE,
    quantile_values: ARRAY<STRUCT<
      quantile: DOUBLE,
      value: DOUBLE
    >>,
    attributes: VARIANT,
    flags: INT
  >,
  metadata VARIANT,
  resource STRUCT<
    attributes: VARIANT,
    dropped_attributes_count: INT
  >,
  resource_schema_url STRING,
  instrumentation_scope STRUCT<
    name: STRING,
    version: STRING,
    attributes: VARIANT,
    dropped_attributes_count: INT
  >,
  metric_schema_url STRING
) USING DELTA
CLUSTER BY (time, service_name)
TBLPROPERTIES (
  'otel.schemaVersion' = 'v2',
  'delta.checkpointPolicy' = 'classic',
  'delta.enableVariantShredding' = 'true', -- optional
  'delta.feature.variantShredding-preview' = 'supported', -- optional
  'delta.feature.variantType-preview' = 'supported' -- optional
);

Creare un'entità servizio e concedere le autorizzazioni

Configurare un principale del servizio con le credenziali OAuth e concedergli l'accesso alle tue tabelle. Per ulteriori informazioni sulla configurazione di un'entità di servizio, vedere Autorizzare l'accesso di un'entità di servizio per Azure Databricks con OAuth.

Concedere al principale del servizio l'accesso al catalogo, allo schema e a ogni tabella. Concedere ALL PRIVILEGES non è sufficiente. È necessario concedere MODIFY in modo esplicito e SELECT in ogni tabella.

GRANT USE CATALOG ON CATALOG <catalog> TO `<service-principal-uuid>`;
GRANT USE SCHEMA ON SCHEMA <catalog>.<schema> TO `<service-principal-uuid>`;
GRANT MODIFY, SELECT ON TABLE <catalog>.<schema>.<prefix>_otel_spans TO `<service-principal-uuid>`;
GRANT MODIFY, SELECT ON TABLE <catalog>.<schema>.<prefix>_otel_logs TO `<service-principal-uuid>`;
GRANT MODIFY, SELECT ON TABLE <catalog>.<schema>.<prefix>_otel_metrics TO `<service-principal-uuid>`;

Configurare l'utilità di esportazione

Gli esempi seguenti usano la strumentazione zero-code di OpenTelemetry per raccogliere e inoltrare automaticamente tracce, log e metriche a Zerobus Ingest senza apportare modifiche al codice all'applicazione. È anche possibile usare altri esportatori compatibili con OTLP che supportano gRPC e intestazioni personalizzate di metadati.

Intestazioni obbligatorie

Tutte le richieste OTLP devono includere le intestazioni di metadati seguenti:

  • x-databricks-zerobus-table-name: nome completo della tabella del catalogo Unity in formato <catalog>.<schema>.<table>. Ogni richiesta è destinata a una singola tabella.
  • Authorization: token di connessione OAuth generato dalle credenziali dell'entità servizio.

Per generare un token portatore statico dalle credenziali dell'entità servizio, vedere Authorize service principal access to Azure Databricks with OAuth. I token statici scadono dopo un'ora. Per le applicazioni a esecuzione prolungata, vedere Agente di raccolta OpenTelemetry con aggiornamento automatico dei token.

Configurazione delle variabili

Definire queste variabili prima di eseguire uno degli esempi seguenti:

Variable Esempio
DATABRICKS_CLIENT_ID abc123-... (ID app dell'entità servizio)
DATABRICKS_CLIENT_SECRET dose1234...
WORKSPACE_URL adb-1234567890123456.12.azuredatabricks.net
WORKSPACE_ID 1234567890123456
REGION eastus
CATALOG my_catalog
SCHEMA my_schema
TABLE_PREFIX my_prefix

È possibile definire queste variabili come variabili di ambiente usando Bash. Per esempio:

export DATABRICKS_CLIENT_ID="<your-client-id>"
export DATABRICKS_CLIENT_SECRET="<your-client-secret>"

Avvio rapido con il token statico

L'esempio seguente usa un token di connessione statico per ogni tipo di segnale (tracce, log, metriche). Prima di eseguire questo esempio, genera i token dai dati di accesso per il principale del servizio. Consulta Autorizzare l'accesso del principale del servizio ad Azure Databricks con OAuth.

Usare questo approccio per pipeline di breve durata o ad hoc in cui la gestione dell'aggiornamento dei token non rappresenta un problema. I token OAuth statici scadono dopo un'ora e non sono adatti per i processi a esecuzione prolungata. Per i carichi di lavoro di produzione, usare invece l'agente di raccolta OpenTelemetry con l'aggiornamento automatico dei token .

È necessario generare un token separato per ogni tipo di segnale. authorization_details Nel payload sostituire $TABLE_NAME con il nome completo della tabella per ogni segnale, ad esempio ${TABLE_PREFIX}_otel_spans, ${TABLE_PREFIX}_otel_logse ${TABLE_PREFIX}_otel_metrics.

authorization_details=$(cat <<EOF
[{
  "type": "unity_catalog_privileges",
  "privileges": ["USE CATALOG"],
  "object_type": "CATALOG",
  "object_full_path": "$CATALOG"
},
{
  "type": "unity_catalog_privileges",
  "privileges": ["USE SCHEMA"],
  "object_type": "SCHEMA",
  "object_full_path": "$CATALOG.$SCHEMA"
},
{
  "type": "unity_catalog_privileges",
  "privileges": ["SELECT", "MODIFY"],
  "object_type": "TABLE",
  "object_full_path": "$CATALOG.$SCHEMA.$TABLE_NAME"
}]
EOF
)

curl -X POST \
  -u "$DATABRICKS_CLIENT_ID:$DATABRICKS_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "scope=all-apis" \
  -d "resource=api://databricks/workspaces/$WORKSPACE_ID/zerobusDirectWriteApi" \
  --data-urlencode "authorization_details=$authorization_details" \
  "https://$WORKSPACE_URL/oidc/v1/token"

Salvare i tre token di accesso restituiti come TOKEN_SPANS, TOKEN_LOGSe TOKEN_METRICS prima di installare i pacchetti di strumentazione automatica. Eseguire quindi l'applicazione:

OTEL_SERVICE_NAME="my-service" \
OTEL_EXPORTER_OTLP_PROTOCOL="grpc" \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://${WORKSPACE_ID}.zerobus.${REGION}.azuredatabricks.net:443" \
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT="https://${WORKSPACE_ID}.zerobus.${REGION}.azuredatabricks.net:443" \
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT="https://${WORKSPACE_ID}.zerobus.${REGION}.azuredatabricks.net:443" \
OTEL_EXPORTER_OTLP_TRACES_HEADERS="authorization=Bearer ${TOKEN_SPANS},x-databricks-zerobus-table-name=${CATALOG}.${SCHEMA}.${TABLE_PREFIX}_otel_spans" \
OTEL_EXPORTER_OTLP_LOGS_HEADERS="authorization=Bearer ${TOKEN_LOGS},x-databricks-zerobus-table-name=${CATALOG}.${SCHEMA}.${TABLE_PREFIX}_otel_logs" \
OTEL_EXPORTER_OTLP_METRICS_HEADERS="authorization=Bearer ${TOKEN_METRICS},x-databricks-zerobus-table-name=${CATALOG}.${SCHEMA}.${TABLE_PREFIX}_otel_metrics" \
OTEL_TRACES_EXPORTER="otlp" \
OTEL_METRICS_EXPORTER="otlp" \
OTEL_LOGS_EXPORTER="otlp" \
opentelemetry-instrument python my_app.py

Agente di raccolta OpenTelemetry con aggiornamento automatico dei token

I token OAuth di Databricks scadono dopo un'ora. Anziché gestire l'aggiornamento dei token nel codice dell'applicazione, distribuisci un OpenTelemetry Collector come proxy tra l'applicazione e Zerobus Ingest. Il Collector usa il oauth2clientauthextension per coniare un token dalle credenziali dell'entità del servizio principale all'avvio del sistema e aggiornarlo automaticamente prima che scada.

Questo è l'approccio consigliato per carichi di lavoro a esecuzione prolungata e di produzione. A differenza dell'approccio al token statico, l'agente di raccolta gestisce automaticamente l'acquisizione e l'aggiornamento dei token OAuth. Il codice dell'applicazione non richiede modifiche.

L'agente di raccolta si trova tra l'applicazione e Zerobus Ingest. L'applicazione invia OTLP in chiaro al Collector su localhost:4317 senza autenticazione. Il Collector aggiunge il token OAuth e l'intestazione di tabella a ogni richiesta e la inoltra all'endpoint Zerobus Ingest.

Configurazione del raccoglitore

Creare un collector.yaml file per configurare il collettore:

extensions:
  oauth2client/spans:
    client_id: ${env:DATABRICKS_CLIENT_ID}
    client_secret: ${env:DATABRICKS_CLIENT_SECRET}
    token_url: https://${env:WORKSPACE_URL}/oidc/v1/token
    scopes: ['all-apis']
    endpoint_params:
      resource: 'api://databricks/workspaces/${env:WORKSPACE_ID}/zerobusDirectWriteApi'
      authorization_details:
        - '[{"type":"unity_catalog_privileges","privileges":["USE CATALOG"],"object_type":"CATALOG","object_full_path":"${env:CATALOG}"},{"type":"unity_catalog_privileges","privileges":["USE SCHEMA"],"object_type":"SCHEMA","object_full_path":"${env:CATALOG}.${env:SCHEMA}"},{"type":"unity_catalog_privileges","privileges":["SELECT","MODIFY"],"object_type":"TABLE","object_full_path":"${env:CATALOG}.${env:SCHEMA}.${env:TABLE_PREFIX}_otel_spans"}]'

  oauth2client/logs:
    client_id: ${env:DATABRICKS_CLIENT_ID}
    client_secret: ${env:DATABRICKS_CLIENT_SECRET}
    token_url: https://${env:WORKSPACE_URL}/oidc/v1/token
    scopes: ['all-apis']
    endpoint_params:
      resource: 'api://databricks/workspaces/${env:WORKSPACE_ID}/zerobusDirectWriteApi'
      authorization_details:
        - '[{"type":"unity_catalog_privileges","privileges":["USE CATALOG"],"object_type":"CATALOG","object_full_path":"${env:CATALOG}"},{"type":"unity_catalog_privileges","privileges":["USE SCHEMA"],"object_type":"SCHEMA","object_full_path":"${env:CATALOG}.${env:SCHEMA}"},{"type":"unity_catalog_privileges","privileges":["SELECT","MODIFY"],"object_type":"TABLE","object_full_path":"${env:CATALOG}.${env:SCHEMA}.${env:TABLE_PREFIX}_otel_logs"}]'

  oauth2client/metrics:
    client_id: ${env:DATABRICKS_CLIENT_ID}
    client_secret: ${env:DATABRICKS_CLIENT_SECRET}
    token_url: https://${env:WORKSPACE_URL}/oidc/v1/token
    scopes: ['all-apis']
    endpoint_params:
      resource: 'api://databricks/workspaces/${env:WORKSPACE_ID}/zerobusDirectWriteApi'
      authorization_details:
        - '[{"type":"unity_catalog_privileges","privileges":["USE CATALOG"],"object_type":"CATALOG","object_full_path":"${env:CATALOG}"},{"type":"unity_catalog_privileges","privileges":["USE SCHEMA"],"object_type":"SCHEMA","object_full_path":"${env:CATALOG}.${env:SCHEMA}"},{"type":"unity_catalog_privileges","privileges":["SELECT","MODIFY"],"object_type":"TABLE","object_full_path":"${env:CATALOG}.${env:SCHEMA}.${env:TABLE_PREFIX}_otel_metrics"}]'

exporters:
  otlp/spans:
    endpoint: ${env:WORKSPACE_ID}.zerobus.${env:REGION}.azuredatabricks.net:443
    auth:
      authenticator: oauth2client/spans
    headers:
      x-databricks-zerobus-table-name: '${env:CATALOG}.${env:SCHEMA}.${env:TABLE_PREFIX}_otel_spans'

  otlp/logs:
    endpoint: ${env:WORKSPACE_ID}.zerobus.${env:REGION}.azuredatabricks.net:443
    auth:
      authenticator: oauth2client/logs
    headers:
      x-databricks-zerobus-table-name: '${env:CATALOG}.${env:SCHEMA}.${env:TABLE_PREFIX}_otel_logs'

  otlp/metrics:
    endpoint: ${env:WORKSPACE_ID}.zerobus.${env:REGION}.azuredatabricks.net:443
    auth:
      authenticator: oauth2client/metrics
    headers:
      x-databricks-zerobus-table-name: '${env:CATALOG}.${env:SCHEMA}.${env:TABLE_PREFIX}_otel_metrics'

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

processors:
  batch:
    timeout: 5s # adjust as needed
    send_batch_size: 10 # adjust as needed

service:
  extensions: [oauth2client/spans, oauth2client/logs, oauth2client/metrics]
  pipelines:
    traces:
      receivers: [otlp] # adjust as needed
      processors: [batch]
      exporters: [otlp/spans]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/logs]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/metrics]

Eseguire quindi l'agente di raccolta:

./otelcol-contrib --config collector.yaml

Instrumentare l'applicazione

Impostare le variabili necessarie prima di eseguire questo esempio di codice. Installare quindi i pacchetti di strumentazione automatica ed eseguire l'applicazione.

OTEL_SERVICE_NAME=my-service \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
OTEL_TRACES_EXPORTER=otlp \
OTEL_METRICS_EXPORTER=otlp \
OTEL_LOGS_EXPORTER=otlp \
opentelemetry-instrument python my_app.py

Passaggi successivi

  • Last updated on