OpenTelemetry do Azure Monitor para JavaScript

Como começar

Instalar o pacote

npm install @azure/monitor-opentelemetry

Ambientes com suporte no momento

• Versões LTS do Node.js

• Tempos de execução suportados pelo OpenTelemetry

Aviso: Este SDK só funciona para ambientes Node.js. Use o SDK do 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 importar qualquer outra coisa. Pode haver perda de telemetria resultante se outras bibliotecas forem importadas primeiro.

import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } 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 APPLICATIONINSIGHTS_CONNECTION_STRINGde ambiente .

Configuração

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

const resource = resourceFromAttributes({ 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);

{
  http: { enabled: true },
  azureSdk: { enabled: true },
  mongoDb: { enabled: true },
  mySql: { enabled: true },
  postgreSql: { enabled: true },
  redis: { enabled: true },
  redis4: { enabled: true },
  bunyan: { enabled: false }, 
  winston: { enabled: false } 
}
      

        
{ 
  enabled: false, 
  connectionString: "" 
}
        
      

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, Ex: node_modules/@azure/monitor-opentelemetry. Esses valores de configuração serão aplicados a todas as instâncias AzureMonitorOpenTelemetryClient.

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

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

process.env["APPLICATIONINSIGHTS_CONFIGURATION_FILE"] = "path/to/customConfig.json";

Bibliotecas de instrumentação

As seguintes bibliotecas de Instrumentação do OpenTelemetry estão incluídas como parte do OpenTelemetry do Azure Monitor.

Nota: As instrumentações do SDK do Azure, MongoDB, MySQL, PostgreSQL, Redis e Redis-4 são habilitadas por padrão para rastreamento distribuído. A instrumentação HTTP/HTTPS também é habilitada por padrão. Todas as outras instrumentações são desativadas por padrão e podem ser habilitadas configurando enabled: true as opções de instrumentação.

Aviso: As bibliotecas de instrumentação são baseadas em especificações experimentais do OpenTelemetry. O compromisso de suporte de visualização da Microsoft é garantir que as bibliotecas a seguir emitam dados para o Application Insights do Azure Monitor, 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
• Azure SDK

Métricas

• HTTP/HTTPS

Registros

• Bunyan

• Winston

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

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

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

Carregador do SDK do navegador do Application Insights

O Carregador de SDK do Navegador do Application Insights permite que você injete o SDK da Web nas 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 servidor resonse contém tags 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)

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 dos atributos de Recurso do OpenTelemetry .

import { emptyResource } from "@opentelemetry/resources";
import {
  ATTR_SERVICE_NAME,
  SEMRESATTRS_SERVICE_NAMESPACE,
  SEMRESATTRS_SERVICE_INSTANCE_ID,
} from "@opentelemetry/semantic-conventions";
import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } from "@azure/monitor-opentelemetry";

// ----------------------------------------
// Setting role name and role instance
// ----------------------------------------
const customResource = emptyResource();
customResource.attributes[ATTR_SERVICE_NAME] = "my-helloworld-service";
customResource.attributes[SEMRESATTRS_SERVICE_NAMESPACE] = "my-namespace";
customResource.attributes[SEMRESATTRS_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 span, use uma das duas maneiras a seguir:

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

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

Ponta: A vantagem de usar opções fornecidas por 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 oferece aos usuários acesso ao próprio httpRequestMessage. Eles podem selecionar qualquer coisa nela e armazenar como um atributo.

Adicionar uma propriedade personalizada a um Trace

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

Usar um processador personalizado:

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

class SpanEnrichingProcessor implements SpanProcessor {
  async forceFlush(): Promise<void> {
    // Flush code here
  }
  async shutdown(): Promise<void> {
    // shutdown code here
  }
  onStart(_span: Span): void {}
  onEnd(span: ReadableSpan): void {
    span.attributes["CustomDimension1"] = "value1";
    span.attributes["CustomDimension2"] = "value2";
    span.attributes[SEMATTRS_HTTP_CLIENT_IP] = "<IP Address>";
  }
}

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

useAzureMonitor(options);

Adicionar 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 { SpanProcessor, ReadableSpan } from "@opentelemetry/sdk-trace-base";
import { Span, Context, trace } from "@opentelemetry/api";
import { AI_OPERATION_NAME } from "@azure/monitor-opentelemetry-exporter";
import { LogRecordProcessor, SdkLogRecord } from "@opentelemetry/sdk-logs";
import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } from "@azure/monitor-opentelemetry";

class SpanEnrichingProcessor implements SpanProcessor {
  async forceFlush(): Promise<void> {
    // Flush code here
  }
  async shutdown(): Promise<void> {
    // shutdown code here
  }
  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.setAttribute(AI_OPERATION_NAME, (parentSpan as unknown as ReadableSpan).name);
    }
  }
  onEnd(_span: ReadableSpan): void {}
}

class LogRecordEnrichingProcessor implements LogRecordProcessor {
  async forceFlush(): Promise<void> {
    // Flush code here
  }
  async shutdown(): Promise<void> {
    // shutdown code here
  }
  onEmit(_logRecord: SdkLogRecord, _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.
      _logRecord.setAttribute(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);

Telemetria de filtro

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 seguinte exemplo mostra como excluir uma determinada URL do rastreamento usando a biblioteca de instrumentação HTTP/HTTPS:

   import { HttpInstrumentationConfig } from "@opentelemetry/instrumentation-http";
   import { IncomingMessage, RequestOptions } from "node:http";
   import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } from "@azure/monitor-opentelemetry";
   
   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 impedir que determinados intervalos sejam exportados. Para marcar intervalos para que não sejam exportados, defina TraceFlag como DEFAULT. Use o exemplo de adição de propriedade personalizada, mas substitua as seguintes linhas de código:

   import { SpanProcessor, ReadableSpan } from "@opentelemetry/sdk-trace-base";
   import { Span, Context, SpanKind, TraceFlags } from "@opentelemetry/api";
   
   class SpanEnrichingProcessor implements SpanProcessor {
     async forceFlush(): Promise<void> {
       // Force flush code here
     }
     onStart(_span: Span, _parentContext: Context): void {
       // Normal code here
     }
     async shutdown(): Promise<void> {
       // Shutdown code here
     }
     onEnd(span: ReadableSpan): void {
       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

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

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

Cuidado: Os 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 { metrics, ObservableResult } from "@opentelemetry/api";

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

const histogram = meter.createHistogram("histogram");
const counter = meter.createCounter("counter");
const gauge = meter.createObservableGauge("gauge");
gauge.addCallback((observableResult: ObservableResult) => {
  const 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 dão suporte automaticamente a exceções ao 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 seu código normalmente não são relatadas e você pode querer relatá-las e, assim, chamar a atenção para elas em experiências relevantes, incluindo a folha de falhas e a 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");

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

Resolução de problemas

Autodiagnóstico

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

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

process.env["APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVEL"] = "VERBOSE";
process.env["APPLICATIONINSIGHTS_LOG_DESTINATION"] = "file";
process.env["APPLICATIONINSIGHTS_LOGDIR"] = "path/to/logs";

useAzureMonitor();

APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVELA variável de ambiente pode ser usada para definir o nível de log desejado, suportando os seguintes valores: NONE, ERROR, WARN, INFO, DEBUGVERBOSE , e ALL.

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

Exemplos

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

Conceitos principais

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

Registro de plug-ins

Para ver se um plug-in já foi criado para uma biblioteca que você está usando, consulte o OpenTelemetry Registry.

Se você não puder colocar sua biblioteca no registro, sinta-se à 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.