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

• Tempos de execução com suporte do OpenTelemetry

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

Confira nossa política de suporte para 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 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);

As opções podem ser definidas usando o arquivo applicationinsights.json de configuração localizado na pasta raiz da pasta de instalação do @azure/monitor-opentelemetry pacote, por exemplo: 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 a 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 estã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. O compromisso de suporte à versão prévia da Microsoft é garantir que as bibliotecas listadas a seguir emitam dados para o Application Insights do Azure Monitor, mas é possível que alterações interruptivas ou mapeamento experimentais bloqueiem alguns elementos de dados.

Rastreamento distribuído

• HTTP/HTTPS
• MongoDB
• MySQL
• Postgres
• Redis
• Redis-4
• 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 Navegador do Application Insights permite injetar o SDK da Web em respostas do servidor de nó quando as seguintes condições forem verdadeiras:

• A resposta tem código de status 200.
• O método de resposta é GET.
• A resposta do servidor tem o Conent-Type cabeçalho html.
• O resso do servidor contém as marcas e .
• A resposta não contém os pontos de extremidade CDN de instrumentação 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 de atributos de recurso 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, confira Convenções de semântica de recursos.

Modificar telemetria

Esta seção explica como modificar a telemetria.

Adicionar atributos de intervalo

Adicione atributos de intervalo de uma destas maneiras:

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

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

Ponta: A vantagem de usar as opções fornecidas pelas bibliotecas de instrumentação, quando elas estão disponíveis, é que todo o contexto está disponível. Assim, os usuários podem optar por adicionar ou filtrar mais atributos. Por exemplo, a opção enriquecer na biblioteca de instrumentação do HttpClient dá aos usuários acesso à httpRequestMessage. Eles podem selecionar qualquer coisa nela e armazenar como um atributo.

Adicionar uma propriedade personalizada em um rastreamento

Todos os atributos adicionados aos intervalos são exportados como propriedades personalizadas.

Usar 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);

Filtrar telemetria

Use as maneiras a seguir de filtrar a telemetria antes que ela saia do aplicativo.

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

   O seguinte exemplo mostra como excluir uma determinada URL do rastreamento 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 span personalizado para excluir determinadas extensões de serem exportadas. Para marcar intervalos para que não sejam exportados, defina TraceFlag como DEFAULT. Use o exemplo adicionar propriedade personalizada, 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 aplicativo.

Adicionar métricas personalizadas

É aconselhável coletar métricas além do que é coletado pelas 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 em Métricas Explorer. Esse requisito é válido ao usar a API de Métrica do 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.

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

A Especificação do OpenTelemetry descreve os instrumentos e fornece exemplos de quando 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

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

import { useAzureMonitor } from "@azure/monitor-opentelemetry";
import { trace } 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);
}

Solução de 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_LEVELA varialbe do ambiente pode ser usada para definir o nível de log desejado, dando suporte aos seguintes valores: NONE, ERROR, , WARN, INFO, DEBUGVERBOSE e ALL.

Os logs podem ser colocados no arquivo local usando APPLICATIONINSIGHTS_LOG_DESTINATION a 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 a variável de ambiente.

Exemplos

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

Principais conceitos

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

Registro de plug-in

Para ver se um plug-in já foi feito para uma biblioteca que você está usando, marcar o 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.

Contribuição

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