Partilhar via

Azure Monitor OpenTelemetry para JavaScript

Versão npm

Como Começar

Instale o pacote

npm install @azure/monitor-opentelemetry

Ambientes atualmente suportados

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

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

Pré-requisitos

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);
Opção Descrição Predefinido
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
instrumentationOptions Configuração de bibliotecas de instrumentação. Mais informações aqui 

{
  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 } 
}
browserSdkLoaderOptions Permitir a configuração de Instrumentações Web. 
        
{ 
  enabled: false, 
  connectionString: "" 
}
resource Recurso OpenTelemetry (Recurso OpenTelemetry ). Mais informações aqui
enableLiveMetrics Ativar/desativar métricas em tempo real. true
enableStandardMetrics Ativar/desativar métricas padrão. true
logRecordProcessors Matriz de processadores de registro de log para registrar no provedor de logger global.
spanProcessors Matriz de processadores span para registro no provedor de rastreador global.
enableTraceBasedSamplingForLogs Habilite a amostragem de log com base no rastreamento. false
enablePerformanceCounters Habilite contadores de desempenho. true

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 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"] = "path/to/customConfig.json";

Bibliotecas de instrumentação

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

Observação: 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 está habilitada por padrão. Todas as outras instrumentações são desativadas por padrão e podem ser ativadas definindo enabled: true as opções de instrumentação.

Atenção: As bibliotecas de instrumentação são baseadas em especificações experimentais OpenTelemetry . O compromisso de suporte de visualização 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

Métricas

Registos

Outras Instrumentações OpenTelemetry estão disponíveis aqui e podem ser adicionadas usando TracerProvider no 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 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 estado 200.
  • O método de resposta é GET.
  • A resposta do servidor tem o Conent-Type cabeçalho html.
  • Server resonse contém ambas as tags e .
  • A resposta não contém os pontos de extremidade CDN de instrumentação web atuais / de backup. (pontos de extremidade atuais e de backup da CDN de instrumentação da Web aqui)

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

Defina o Nome da Função na Nuvem e a Instância da Função na 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 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 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 de enriquecimento na biblioteca de instrumentação HttpClient dá aos utilizadores 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 adicionados às extensões são exportados como propriedades personalizadas.

Use 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 span 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 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 { 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 span personalizado para excluir determinadas spans de serem exportadas. 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 { 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;
    }
  }
}

Custom telemetry (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 pelas 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 OpenTelemetry Metric Instruments.

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 Mediano
UpDownCounter (somente Python e Node.js) Soma
UpDownCounter assíncrono (somente Python e Node.js) Soma

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

A Especificação OpenTelemetry descreve os instrumentos e fornece exemplos de quando se pode usar cada um.

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

const 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";

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 no arquivo local usando APPLICATIONINSIGHTS_LOG_DESTINATION a variável de ambiente, os valores suportados são file e file+console, um arquivo nomeado 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.

Conceitos-chave

Para obter mais informações sobre o projeto OpenTelemetry , consulte as especificações 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 puder sua biblioteca no registro, sinta-se à vontade para sugerir uma nova solicitação de plug-in em opentelemetry-js-contrib.

Contribuir

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

  • Last updated on