OpenTelemetry do Azure Monitor para JavaScript

Introdução

Instalar o pacote

npm install @azure/monitor-opentelemetry

Ambientes com suporte no momento

• versões lts do Node.js

• de runtimes com suporte do OpenTelemetry

aviso : esse SDK só funciona para ambientes de Node.js. Use o do SDK javaScript do Application Insights para cenários da Web e do navegador.

Consulte nossa política de suporte para obter mais detalhes.

Pré-requisitos

• Uma assinatura do Azure
• Um workspace do Application Insights

Habilitar o cliente OpenTelemetry do Azure Monitor

Importante:useAzureMonitor deve ser chamado antes de você importar qualquer outra coisa. Pode haver perda de telemetria resultante se outras bibliotecas forem importadas primeiro.

import { useAzureMonitor, AzureMonitorOpenTelemetryOptions } from "@azure/monitor-opentelemetry";

const options: AzureMonitorOpenTelemetryOptions = {
  azureMonitorExporterOptions: {
    connectionString:
      process.env["APPLICATIONINSIGHTS_CONNECTION_STRING"] || "<your connection string>",
  },
};
useAzureMonitor(options);

• A cadeia de conexão pode ser definida usando a variável de ambiente APPLICATIONINSIGHTS_CONNECTION_STRING

Configuração

import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } from "@azure/monitor-opentelemetry";
import { Resource } from "@opentelemetry/resources";

const resource = new Resource({ testAttribute: "testValue" });
const options: AzureMonitorOpenTelemetryOptions = {
  azureMonitorExporterOptions: {
    // Offline storage
    storageDirectory: "c://azureMonitor",
    // Automatic retries
    disableOfflineStorage: false,
    // Application Insights Connection String
    connectionString:
      process.env["APPLICATIONINSIGHTS_CONNECTION_STRING"] || "<your connection string>",
  },
  samplingRatio: 1,
  instrumentationOptions: {
    // Instrumentations generating traces
    azureSdk: { enabled: true },
    http: { enabled: true },
    mongoDb: { enabled: true },
    mySql: { enabled: true },
    postgreSql: { enabled: true },
    redis: { enabled: true },
    redis4: { enabled: true },
    // Instrumentations generating logs
    bunyan: { enabled: true },
    winston: { enabled: true },
  },
  enableLiveMetrics: true,
  enableStandardMetrics: true,
  browserSdkLoaderOptions: {
    enabled: false,
    connectionString: "",
  },
  resource: resource,
  logRecordProcessors: [],
  spanProcessors: [],
};

useAzureMonitor(options);

Propriedade	Descrição	Inadimplência
azureMonitorExporterOptions	Configuração do exportador opentelemetry do Azure Monitor. Mais informações aqui
samplingRatio	A taxa de amostragem deve ter um valor no intervalo [0,1], 1 o que significa que todos os dados serão amostrados e 0 todos os dados de rastreamento serão amostrados.	1
instrumentationOptions	Permitir a configuração de Instrumentações OpenTelemetry.	{"http": { habilitado: true },"azureSdk": { habilitado: false },"mongoDb": { habilitado: false },"mySql": { habilitado: false },"postgreSql": { habilitado: false },"redis": { habilitado: false },"bunyan": { habilitado: false }, "winston": { habilitado: false } } }
browserSdkLoaderOptions	Permitir a configuração de instrumentações da Web.	{ habilitado: false, connectionString: "" }
recurso	Recurso Opentelemetry. Mais informações aqui
samplingRatio	A taxa de amostragem deve ter um valor no intervalo [0,1], 1 o que significa que todos os dados serão amostrados e 0 todos os dados de rastreamento serão amostrados.	1
enableLiveMetrics	Habilitar/desabilitar métricas dinâmicas.	verdadeiro
enableStandardMetrics	Habilitar/desabilitar métricas padrão.	verdadeiro
logRecordProcessors	Matriz de processadores de registro de log a serem registrados no provedor de agente global.
SpanProcessors	Matriz de processadores de intervalo para se registrar no provedor de rastreamento global.
enableTraceBasedSamplingForLogs	Habilite a amostragem de log com base no rastreamento.	falso

As opções podem ser definidas usando o arquivo de configuração applicationinsights.json localizado na pasta raiz da pasta de instalação do pacote @azure/monitor-opentelemetry, Ex: node_modules/@azure/monitor-opentelemetry. Esses valores de configuração serão aplicados a todas as instâncias do AzureMonitorOpenTelemetryClient.

{
    "samplingRatio": 0.8,
    "enableStandardMetrics": true,
    "enableLiveMetrics": true,
    "instrumentationOptions":{
        "azureSdk": {
            "enabled": false
        }
    },
    ...
}

O arquivo JSON personalizado pode ser fornecido usando APPLICATIONINSIGHTS_CONFIGURATION_FILE variável de ambiente.

process.env.APPLICATIONINSIGHTS_CONFIGURATION_FILE =
  "C:/applicationinsights/config/customConfig.json";

// Application Insights SDK setup....

Bibliotecas de instrumentação

As bibliotecas de Instrumentação OpenTelemetry a seguir são incluídas como parte do OpenTelemetry do Azure Monitor.

Aviso: as bibliotecas de Instrumentação são baseadas em especificações experimentais do OpenTelemetry. A versão prévia da Microsoft compromisso de suporte é garantir que as bibliotecas a seguir emitem dados para o Azure Monitor Application Insights, mas é possível que alterações interruptivas ou mapeamento experimental bloqueiem alguns elementos de dados.

Rastreamento Distribuído

• HTTP/HTTPS
• do MongoDB
• MySQL
• Postgres
• Redis
• Redis-4
• do SDK do Azure

Métricas

• HTTP/HTTPS

Logs

• Bunyan

• Winston

Outras Instrumentações OpenTelemetry estão disponíveis aqui e podem ser adicionadas usando TracerProvider no AzureMonitorOpenTelemetryClient.

import { useAzureMonitor } from "@azure/monitor-opentelemetry";
import { metrics, trace } from "@opentelemetry/api";
import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";

useAzureMonitor();
const instrumentations = [new ExpressInstrumentation()];
registerInstrumentations({
  tracerProvider: trace.getTracerProvider(),
  meterProvider: metrics.getMeterProvider(),
  instrumentations: instrumentations,
});

Carregador do SDK do Application Insights Browser

O Carregador do SDK do Application Insights Browser permite que você insira o SDK da Web nas respostas do servidor de nó quando as seguintes condições forem verdadeiras:

• A resposta tem 200de código de status.
• O método de resposta é GET.
• A resposta do servidor tem o cabeçalho html Conent-Type.
• O resso do servidor contém marcas e .
• A resposta não contém pontos de extremidade cdn de instrumentação web /backup atuais. (pontos de extremidade cdn de instrumentação web atuais e de backup aqui)

Mais informações sobre o uso do carregador do SDK do navegador podem ser encontradas aqui.

Definir o nome da função de nuvem e a instância de função de nuvem

Você pode definir o Nome da Função de Nuvem e a Instância de Função de Nuvem por meio de atributos de Recursos do OpenTelemetry.

import { useAzureMonitor, AzureMonitorOpenTelemetryOptions } from "@azure/monitor-opentelemetry";
import { Resource } from "@opentelemetry/resources";
import { SemanticResourceAttributes } from "@opentelemetry/semantic-conventions";

// ----------------------------------------
// Setting role name and role instance
// ----------------------------------------
const customResource = Resource.EMPTY;
customResource.attributes[SemanticResourceAttributes.SERVICE_NAME] = "my-helloworld-service";
customResource.attributes[SemanticResourceAttributes.SERVICE_NAMESPACE] = "my-namespace";
customResource.attributes[SemanticResourceAttributes.SERVICE_INSTANCE_ID] = "my-instance";

const options: AzureMonitorOpenTelemetryOptions = { resource: customResource };
useAzureMonitor(options);

Para obter informações sobre atributos padrão para recursos, consulte convenções semânticas de recursos.

Modificar telemetria

Esta seção explica como modificar a telemetria.

Adicionar atributos de intervalo

Para adicionar atributos de intervalo, use uma das duas maneiras a seguir:

• Opções de uso fornecidas por bibliotecas de instrumentação.
• Adicione um processador de intervalo personalizado.

Esses atributos podem incluir a adição de uma propriedade personalizada à telemetria.

Dica: A vantagem de usar as opções fornecidas pelas bibliotecas de instrumentação, quando elas estiverem disponíveis, é que todo o contexto está disponível. Como resultado, os usuários podem selecionar para adicionar ou filtrar mais atributos. Por exemplo, a opção de enriquecimento na biblioteca de instrumentação HttpClient dá aos usuários acesso ao httpRequestMessage em si. Eles podem selecionar qualquer coisa nele e armazená-lo como um atributo.

Adicionar uma propriedade personalizada a um rastreamento

Todos os atributos você adicionar a intervalos são exportados como propriedades personalizadas.

Use um processador personalizado:

import { useAzureMonitor, AzureMonitorOpenTelemetryOptions } from "@azure/monitor-opentelemetry";
import { ReadableSpan, Span, SpanProcessor } from "@opentelemetry/sdk-trace-base";
import { SemanticAttributes } from "@opentelemetry/semantic-conventions";

class SpanEnrichingProcessor implements SpanProcessor {
  forceFlush(): Promise<void> {
    return Promise.resolve();
  }
  shutdown(): Promise<void> {
    return Promise.resolve();
  }
  onStart(_span: Span): void {}
  onEnd(span: ReadableSpan) {
    span.attributes["CustomDimension1"] = "value1";
    span.attributes["CustomDimension2"] = "value2";
    span.attributes[SemanticAttributes.HTTP_CLIENT_IP] = "<IP Address>";
  }
}

// Enable Azure Monitor integration.
const options: AzureMonitorOpenTelemetryOptions = {
  // Add the SpanEnrichingProcessor
  spanProcessors: [new SpanEnrichingProcessor()],
};
useAzureMonitor(options);

Adicionar o nome da operação a rastreamentos e logs

Use um processador de intervalo personalizado e um processador de registro de log para anexar e correlacionar o nome da operação de solicitações a dependências e logs.

import { useAzureMonitor, AzureMonitorOpenTelemetryOptions } from "@azure/monitor-opentelemetry";
import { ReadableSpan, Span, SpanProcessor } from "@opentelemetry/sdk-trace-base";
import { LogRecordProcessor } from "@opentelemetry/sdk-logs";
import { SemanticAttributes } from "@opentelemetry/semantic-conventions";
import { AI_OPERATION_NAME } from "@azure/monitor-opentelemetry-exporter";
import { Context, trace } from "@opentelemetry/api";

class SpanEnrichingProcessor implements SpanProcessor {
  forceFlush(): Promise<void> {
    return Promise.resolve();
  }
  shutdown(): Promise<void> {
    return Promise.resolve();
  }
  onStart(_span: Span, _context: Context): void {
    const parentSpan = trace.getSpan(_context);
    if (parentSpan && "name" in parentSpan) {
      // If the parent span has a name we can assume it is a ReadableSpan and cast it.
      _span.attributes[AI_OPERATION_NAME] = (parentSpan as unknown as ReadableSpan).name;
    }
  }
  onEnd(span: ReadableSpan) {}
}

class LogRecordEnrichingProcessor implements LogRecordProcessor {
  forceFlush(): Promise<void> {
    return Promise.resolve();
  }
  shutdown(): Promise<void> {
    return Promise.resolve();
  }
  onEmit(_logRecord, _context): void {
    const parentSpan = trace.getSpan(_context);
    if (parentSpan && "name" in parentSpan) {
      // If the parent span has a name we can assume it is a ReadableSpan and cast it.
      _logRecord.attributes[AI_OPERATION_NAME] = (parentSpan as unknown as ReadableSpan).name;
    }
  }
}

// Enable Azure Monitor integration.
const options: AzureMonitorOpenTelemetryOptions = {
  // Add the SpanEnrichingProcessor
  spanProcessors: [new SpanEnrichingProcessor()],
  logRecordProcessors: [new LogRecordEnrichingProcessor()],
};
useAzureMonitor(options);

Filtrar telemetria

Você pode usar as seguintes maneiras de filtrar a telemetria antes que ela saia do aplicativo.

1. Exclua a opção de URL fornecida por muitas bibliotecas de instrumentação HTTP.

   O exemplo a seguir mostra como excluir uma determinada URL de ser rastreada usando a biblioteca de instrumentação HTTP/HTTPS :

   import {
     useAzureMonitor,
     AzureMonitorOpenTelemetryOptions,
   } from "@azure/monitor-opentelemetry";
   import { IncomingMessage } from "http";
   import { RequestOptions } from "https";
   import { HttpInstrumentationConfig } from "@opentelemetry/instrumentation-http";
   
   const httpInstrumentationConfig: HttpInstrumentationConfig = {
     enabled: true,
     ignoreIncomingRequestHook: (request: IncomingMessage) => {
       // Ignore OPTIONS incoming requests
       if (request.method === "OPTIONS") {
         return true;
       }
       return false;
     },
     ignoreOutgoingRequestHook: (options: RequestOptions) => {
       // Ignore outgoing requests with /test path
       if (options.path === "/test") {
         return true;
       }
       return false;
     },
   };
   const options: AzureMonitorOpenTelemetryOptions = {
     instrumentationOptions: {
       http: httpInstrumentationConfig,
     },
   };
   useAzureMonitor(options);
   

2. Use um processador personalizado. Você pode usar um processador de intervalo personalizado para excluir a exportação de determinados intervalos. Para marcar intervalos para não serem exportados, defina TraceFlag como DEFAULT. Use o exemplo adicionar propriedade personalizada, mas substitua as seguintes linhas de código:

   ```typescript
   ...
   import { SpanKind, TraceFlags } from "@opentelemetry/api";
   import { ReadableSpan, SpanProcessor } from "@opentelemetry/sdk-trace-base";
   
   class SpanEnrichingProcessor implements SpanProcessor {
       ...
   
       onEnd(span: ReadableSpan) {
           if(span.kind == SpanKind.INTERNAL){
               span.spanContext().traceFlags = TraceFlags.NONE;
           }
       }
   }
   ```
   

Telemetria personalizada

Esta seção explica como coletar telemetria personalizada de seu aplicativo.

Adicionar métricas personalizadas

Talvez você queira coletar métricas além do que é coletado por bibliotecas de instrumentação.

A API OpenTelemetry oferece seis "instrumentos" de métrica para abranger uma variedade de cenários de métrica e você precisará escolher o "Tipo de Agregação" correto ao visualizar as métricas no Metrics Explorer. Esse requisito é verdadeiro ao usar a API de Métrica OpenTelemetry para enviar métricas e ao usar uma biblioteca de instrumentação.

A tabela a seguir mostra os tipos de agregação recomendados] para cada um dos Instrumentos de Métrica opentelemetry.

Instrumento OpenTelemetry	Tipo de agregação do Azure Monitor
Balcão	Soma
Contador assíncrono	Soma
Histograma	Média, Soma, Contagem (Max, Min somente para Python e Node.js)
Medidor assíncrono	Média
UpDownCounter (somente Python e Node.js)	Soma
UpDownCounter assíncrono (somente Python e Node.js)	Soma

Cuidado: tipos de agregação além do que é mostrado na tabela normalmente não são significativos.

O especificação OpenTelemetry descreve os instrumentos e fornece exemplos de quando você pode usar cada um deles.

import { useAzureMonitor } from "@azure/monitor-opentelemetry";
import { ObservableResult, metrics } from "@opentelemetry/api";

useAzureMonitor();
const meter = metrics.getMeter("testMeter");

let histogram = meter.createHistogram("histogram");
let counter = meter.createCounter("counter");
let gauge = meter.createObservableGauge("gauge");
gauge.addCallback((observableResult: ObservableResult) => {
  let randomNumber = Math.floor(Math.random() * 100);
  observableResult.observe(randomNumber, { testKey: "testValue" });
});

histogram.record(1, { testKey: "testValue" });
histogram.record(30, { testKey: "testValue2" });
histogram.record(100, { testKey2: "testValue" });

counter.add(1, { testKey: "testValue" });
counter.add(5, { testKey2: "testValue" });
counter.add(3, { testKey: "testValue2" });

Adicionar exceções personalizadas

Selecione bibliotecas de instrumentação que dão suporte automaticamente a exceções ao Application Insights. No entanto, convém relatar manualmente exceções além do relatório de bibliotecas de instrumentação. Por exemplo, as exceções capturadas pelo código não são normalmente não relatadas e talvez você queira denunciá-las e, portanto, chamar a atenção para elas em experiências relevantes, incluindo a folha de falhas e o modo de exibição de transação de ponta a ponta.

import { useAzureMonitor } from "@azure/monitor-opentelemetry";
import { trace, Exception } from "@opentelemetry/api";

useAzureMonitor();
const tracer = trace.getTracer("testMeter");

let span = tracer.startSpan("hello");
try {
  throw new Error("Test Error");
} catch (error) {
  span.recordException(error as Exception);
}

Solucionando problemas

Autodiagnóstico

O OpenTelemetry do Azure Monitor usa o Agente de API OpenTelemetry para logs internos. Para habilitá-lo, use o seguinte código:

import { useAzureMonitor } from "@azure/monitor-opentelemetry";
import { DiagLogLevel } from "@opentelemetry/api";

process.env.APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVEL = "VERBOSE";
process.env.APPLICATIONINSIGHTS_LOG_DESTINATION = "file";
process.env.APPLICATIONINSIGHTS_LOGDIR = "C:/applicationinsights/logs";

useAzureMonitor();

APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVEL variável de ambiente pode ser usada para definir o nível de log desejado, dando suporte aos seguintes valores: NONE, ERROR, WARN, INFO, DEBUG, VERBOSE e ALL.

Os logs podem ser colocados em arquivo local usando APPLICATIONINSIGHTS_LOG_DESTINATION variável de ambiente, os valores com suporte são file e file+console, um arquivo chamado applicationinsights.log será gerado na pasta tmp por padrão, incluindo todos os logs, /tmp para *nix e USERDIR/AppData/Local/Temp para Windows. O diretório de log pode ser configurado usando APPLICATIONINSIGHTS_LOGDIR variável de ambiente.

Exemplos

Para obter exemplos completos de alguns cenários de campeão, consulte a pasta samples/.

Principais conceitos

Para obter mais informações sobre o projeto OpenTelemetry, examine o de Especificações do OpenTelemetry.

Registro de plug-in

Para ver se um plug-in já foi feito para uma biblioteca que você está usando, confira o do Registro OpenTelemetry.

Se você não puder sua biblioteca no Registro, fique à vontade para sugerir uma nova solicitação de plug-in em opentelemetry-js-contrib.

Contribuindo

Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.

impressões