Azure Monitor OpenTelemetry para JavaScript

Primeiros passos

Instalar o pacote

npm install @azure/monitor-opentelemetry

Ambientes atualmente suportados

• versões LTS do Node.js

• OpenTelemetry suportava tempos de execução

Aviso: Este SDK só funciona para ambientes Node.js. Use o SDK JavaScript do Application Insights para cenários da Web e do navegador.

Consulte o nosso de política de suporte para obter mais detalhes.

Pré-requisitos

• Uma assinatura do Azure
• Um espaço de trabalho do Application Insights

Habilitar o Cliente OpenTelemetry do Azure Monitor

Importante:useAzureMonitor deve ser chamado antes de 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 razão de amostragem deve ter um valor no intervalo [0,1], 1 significa que todos os dados serão amostrados e 0 todos os dados de rastreio serão amostrados.	1
instrumentaçãoOpções	Permitir a configuração de Instrumentações OpenTelemetry .	{"http": { enabled: true },"azureSdk": { enabled: false },"mongoDb": { enabled: false },"mySql": { enabled: false },"postgreSql": { enabled: false },"redis": { enabled: false },"bunyan": { enabled: false }, "winston": { enabled: false } }
browserSdkLoaderOptions	Permitir a configuração de Instrumentações Web.	{ enabled: false, connectionString: "" }
recurso	Recurso OpenTelemetry (Recurso OpenTelemetry ). Mais informações aqui
samplingRatio	A razão de amostragem deve ter um valor no intervalo [0,1], 1 significa que todos os dados serão amostrados e 0 todos os dados de rastreio serão amostrados.	1
habilitar LiveMetrics	Ativar/desativar métricas em tempo real.	verdadeiro
enableStandardMetrics	Ativar/desativar métricas padrão.	verdadeiro
logRecordProcessors	Matriz de processadores de registro de log para registrar no provedor de logger global.
spanProcessadores	Matriz de processadores span para registro no provedor de rastreador global.

As opções podem ser definidas usando o arquivo de configuração applicationinsights.json localizado na pasta raiz de @azure/monitor-opentelemetry pasta de instalação do pacote, 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 seguintes bibliotecas de Instrumentação OpenTelemetry estão incluídas como parte do Azure Monitor OpenTelemetry.

Aviso: bibliotecas de instrumentação são baseadas em especificações experimentais OpenTelemetry . O compromisso de visualização suporte da Microsoft é garantir que as bibliotecas a seguir emitam dados para o Azure Monitor Application Insights, mas é possível que alterações significativas ou mapeamento experimental bloqueiem alguns elementos de dados.

Rastreamento distribuído

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

Métricas

• HTTP/HTTPS

Registos

• 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 SDK do navegador do Application Insights

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

• A resposta tem o código de status 200.
• O método de resposta é GET.
• A resposta do servidor tem o cabeçalho html Conent-Type.
• A ressonância do servidor contém as tags e .
• A resposta não contém pontos de extremidade CDN de instrumentação da Web /backup atuais. (pontos de extremidade CDN de instrumentação da Web atuais e de backup 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 atributos de de Recursos 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 span

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

• Use as opções fornecidas pelas bibliotecas de instrumentação .
• Adicione um processador span personalizado.

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

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

Adicionar uma propriedade personalizada a um Rastreamento

Todos os atributos você adiciona a extensões 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);

Telemetria do filtro

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

1. Exclua a opção 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 span personalizado para excluir determinadas extensões da exportação. Para marcar extensões para não serem exportadas, defina TraceFlag como DEFAULT. Use o exemplo de propriedade personalizada add , mas substitua as seguintes linhas de código:

   ...
   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 do seu aplicativo.

Adicionar métricas personalizadas

Você pode querer coletar métricas além do que é coletado por bibliotecas de instrumentação.

A API OpenTelemetry oferece seis "instrumentos" métricos para cobrir uma variedade de cenários métricos e você precisará escolher o "Tipo de agregação" correto ao visualizar 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 Métricos OpenTelemetry .

Instrumento OpenTelemetry	Tipo de agregação do Azure Monitor
Contador	Soma
Contador assíncrono	Soma
Histograma	Média, Soma, Contagem (Max, Min apenas 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 OpenTelemetry Specification descreve os instrumentos e fornece exemplos de quando você pode usar cada um.

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

Bibliotecas de instrumentação selecionadas suportam automaticamente exceções ao Application Insights. No entanto, convém relatar manualmente exceções além do que as bibliotecas de instrumentação relatam. Por exemplo, as exceções detetadas pelo seu código não são normalmente não relatadas, e você pode querer relatá-las e, assim, chamar a atenção para elas em experiências relevantes, incluindo a lâmina de falhas e a visualizaçã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);
}

Solução de problemas

Autodiagnóstico

O Azure Monitor OpenTelemetry usa o OpenTelemetry API Logger 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 varialbe do ambiente pode ser usado para definir o nível de log desejado, suportando os 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 suportados 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/.

Conceitos-chave

Para obter mais informações sobre o projeto OpenTelemetria, consulte o Especificações do OpenTelemetry.

Registro de plug-ins

Para ver se um plugin já foi feito para uma biblioteca que você está usando, verifique o OpenTelemetry Registry.

Se você não pode sua biblioteca no registro, sinta-se livre para sugerir uma nova solicitação de plugin em opentelemetry-js-contrib.

Contribuição

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