OpenTelemetry em produção: pare de depurar no escuro

spinny:~/writing $ vim opentelemetry-nodejs-observability-guide.md

1~
2A primeira vez que você realmente precisa de observabilidade não é quando olha calmamente para um painel. É quando um usuário escreve “checkout lento”, o gráfico de erros parece normal e nos logs você encontra apenas uma linha de mensagens desconectadas.
3~
4OpenTelemetry foi criado para evitar esse momento: não para ter mais gráficos, mas para conectar as peças. Uma solicitação entra no API, chama um banco de dados, passa por um provedor externo, publica um trabalho na fila e talvez falhe três serviços depois. Sem rastreamento distribuído, você reconstrói essa história manualmente. Com OpenTelemetry pelo menos você tem um mapa.
5~
6## A questão não é o trace, é a história
7~
8Um trace é uma sequência de span. Dito assim, parece frio. Na prática, cada span é um pedaço da história: `POST /checkout`, `SELECT inventory`, `call payment provider`, `publish order.created`.
9~
10O valor surge quando você começa a responder perguntas reais:
11~
12- qual serviço externo está desacelerando?
13- os erros vêm de uma versão específica?
14- o problema afecta todos ou apenas um inquilino?
15- uma nova tentativa está ocultando um tempo limite?
16- o trabalho assíncrono começa, mas depois morre em outro lugar?
17~
18Essas questões não podem ser resolvidas com um `console.log` lançado às pressas. Na verdade, muitas vezes o registro adicionado em caso de emergência ajuda você hoje e se torna um barulho amanhã.
19~
20## Como eu colocaria isso em um aplicativo Node.js
21~
22A configuração mais saudável é simples: o aplicativo produz telemetria, o Collector decide para onde enviá-la.
23~
24```text
25Node.js app -> OpenTelemetry Collector -> backend di observability
26```
27~
28Por que não exportar diretamente para o fornecedor? Porque a princípio parece mais rápido, depois você percebe que cada serviço tem configurações diferentes, tentativas diferentes, filtros diferentes e nenhum ponto central para remover dados sensíveis ou alterar o destino.
29~
30O Collector é chato da maneira certa. Ele recebe OTLP, faz lotes, pode filtrar, pode fazer amostragem, pode adicionar atributos comuns e pode exportar para vários sistemas.
31~
32## Autoinstrumentação: boa, mas não suficiente
33~
34Em Node.js eu começaria com a instrumentação automática. Dá visibilidade imediata sobre HTTP, estruturas suportadas, bancos de dados e bibliotecas comuns.
35~
36```bash
37npm install @opentelemetry/sdk-node \
38  @opentelemetry/auto-instrumentations-node \
39  @opentelemetry/exporter-trace-otlp-http
40```
41~
42Então você inicializa o SDK antes do resto do aplicativo:
43~
44```typescript
45import { NodeSDK } from '@opentelemetry/sdk-node';
46import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
47import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
48~
49const sdk = new NodeSDK({
50  traceExporter: new OTLPTraceExporter({
51    url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
52  }),
53  instrumentations: [getNodeAutoInstrumentations()],
54});
55~
56sdk.start();
57```
58~
59No entanto, isso vê a estrutura, não o seu produto. Ele sabe que você fez uma consulta, mas não sabe que a consulta estava em "criar pedido" ou "renovar assinatura". Para isso você precisa de span manuais nos pontos onde o domínio conta.
60~
61```typescript
62const span = tracer.startSpan('checkout.create_order');
63~
64try {
65  span.setAttribute('cart.items_count', input.items.length);
66  const order = await createOrder(input);
67  span.setAttribute('order.id', order.id);
68  return order;
69} catch (error) {
70  span.recordException(error as Error);
71  throw error;
72} finally {
73  span.end();
74}
75```
76~
77Eu não colocaria manuais span em lugar nenhum. Eu os colocaria onde, às três da manhã, gostaria de entender o que aconteceu sem ler metade do código base.
78~
79## Três regras que evitam muito caos
80~
81Primeira regra: cada serviço deve ter `service.name`, ambiente e versão. Parece trivial, mas sem esses atributos um trace é muito menos útil. Quando uma implantação quebra alguma coisa, você deseja filtrar por versão em dois segundos.
82~
83Segunda regra: não coloque dados confidenciais nos atributos. E-mails, tokens, cargas inteiras e endereços não devem acabar em um back-end de observabilidade por acidente. Se você precisar identificar um usuário, considere IDs internos, hash ou campos menos confidenciais.
84~
85Terceira regra: preste atenção à cardinalidade. `user.id` como um atributo de trace pode fazer sentido. Como rótulo de métrica, pode destruir seus custos e desempenho.
86~
87## Métricas: poucas, mas boas
88~
89Eu começaria com métricas muito práticas:
90~
91- taxas, erros e duração das solicitações;
92- latência de dependências externas;
93- número de timeouts e novas tentativas;
94- profundidade das caudas;
95- duração do trabalho;
96- porcentagem de erros por versão.
97~
98O resto é adicionado quando necessário. Painéis cheios de gráficos que ninguém olha são móveis, não observabilidade.
99~
100## Logs: ainda úteis, mas vinculados
101~
102Os registros não desaparecem. Eles simplesmente se tornam muito mais úteis quando carregam `trace_id` e `span_id`. Portanto, você pode começar a partir de um log de erros e abrir o trace, ou começar a partir de um trace lento e ler apenas os logs produzidos nesse caminho.
103~
104Sem correlação, você está procurando agulhas. Com a correlação, pelo menos você sabe em qual gaveta procurar.
105~
106## A lista de verificação que eu usaria antes de dizer "estamos cobertos"
107~
108- O trace na verdade cruza vários serviços.
109- Os registros incluem `trace_id` e `span_id`.
110- O Collector está configurado com lotes e limites de memória.
111- Os erros são registrados em span.
112- Existe uma política de amostragem.
113- As métricas têm cardinalidade controlada.
114- Dados confidenciais são filtrados.
115- Os alertas começam a partir dos sintomas do usuário, não de gráficos aleatórios.
116~
117## Conclusão
118~
119OpenTelemetry não resolve problemas de produção por si só. Mas a maneira como você lida com eles muda. Em vez de adicionar logs às cegas, você começa a seguir o caminho real de uma solicitação.
120~
121Para mim o sinal de que está funcionando é simples: quando algo acontece, a equipe para de perguntar “para onde estamos olhando?” e começa a perguntar "por que essa peça está lenta?". É aí que a observabilidade se torna uma ferramenta, não uma coleção de painéis.
122~
123## Fontes
124~
125- [OpenTelemetry: Overview](https://opentelemetry.io/docs/specs/otel/overview/)
126- [OpenTelemetry Collector: Configuration](https://opentelemetry.io/docs/collector/configuration/)
127- [OpenTelemetry JavaScript: Node.js getting started](https://opentelemetry.io/docs/languages/js/getting-started/nodejs/)
128- [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/concepts/semantic-conventions/)
129~

NORMAL · opentelemetry-nodejs-observability-guide.md [readonly]129 lines · :q to close

2A primeira vez que você realmente precisa de observabilidade não é quando olha calmamente para um painel. É quando um usuário escreve “checkout lento”, o gráfico de erros parece normal e nos logs você encontra apenas uma linha de mensagens desconectadas.

4OpenTelemetry foi criado para evitar esse momento: não para ter mais gráficos, mas para conectar as peças. Uma solicitação entra no API, chama um banco de dados, passa por um provedor externo, publica um trabalho na fila e talvez falhe três serviços depois. Sem rastreamento distribuído, você reconstrói essa história manualmente. Com OpenTelemetry pelo menos você tem um mapa.

6## A questão não é o trace, é a história

8Um trace é uma sequência de span. Dito assim, parece frio. Na prática, cada span é um pedaço da história: `POST /checkout`, `SELECT inventory`, `call payment provider`, `publish order.created`.

10O valor surge quando você começa a responder perguntas reais:

11~

12- qual serviço externo está desacelerando?

13- os erros vêm de uma versão específica?

14- o problema afecta todos ou apenas um inquilino?

15- uma nova tentativa está ocultando um tempo limite?

16- o trabalho assíncrono começa, mas depois morre em outro lugar?

17~

18Essas questões não podem ser resolvidas com um `console.log` lançado às pressas. Na verdade, muitas vezes o registro adicionado em caso de emergência ajuda você hoje e se torna um barulho amanhã.

19~

20## Como eu colocaria isso em um aplicativo Node.js

21~

22A configuração mais saudável é simples: o aplicativo produz telemetria, o Collector decide para onde enviá-la.

23~

24```text

25Node.js app -> OpenTelemetry Collector -> backend di observability

26```

27~

28Por que não exportar diretamente para o fornecedor? Porque a princípio parece mais rápido, depois você percebe que cada serviço tem configurações diferentes, tentativas diferentes, filtros diferentes e nenhum ponto central para remover dados sensíveis ou alterar o destino.

29~

30O Collector é chato da maneira certa. Ele recebe OTLP, faz lotes, pode filtrar, pode fazer amostragem, pode adicionar atributos comuns e pode exportar para vários sistemas.

31~

32## Autoinstrumentação: boa, mas não suficiente

33~

34Em Node.js eu começaria com a instrumentação automática. Dá visibilidade imediata sobre HTTP, estruturas suportadas, bancos de dados e bibliotecas comuns.

35~

36```bash

37npm install @opentelemetry/sdk-node \

38 @opentelemetry/auto-instrumentations-node \

39 @opentelemetry/exporter-trace-otlp-http

40```

41~

42Então você inicializa o SDK antes do resto do aplicativo:

43~

44```typescript

45import { NodeSDK } from '@opentelemetry/sdk-node';

46import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

47import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';

48~

49const sdk = new NodeSDK({

50 traceExporter: new OTLPTraceExporter({

51 url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,

52 }),

53 instrumentations: [getNodeAutoInstrumentations()],

54});

55~

56sdk.start();

57```

58~

59No entanto, isso vê a estrutura, não o seu produto. Ele sabe que você fez uma consulta, mas não sabe que a consulta estava em "criar pedido" ou "renovar assinatura". Para isso você precisa de span manuais nos pontos onde o domínio conta.

60~

61```typescript

62const span = tracer.startSpan('checkout.create_order');

63~

64try {

65 span.setAttribute('cart.items_count', input.items.length);

66 const order = await createOrder(input);

67 span.setAttribute('order.id', order.id);

68 return order;

69} catch (error) {

70 span.recordException(error as Error);

71 throw error;

72} finally {

73 span.end();

74}

75```

76~

77Eu não colocaria manuais span em lugar nenhum. Eu os colocaria onde, às três da manhã, gostaria de entender o que aconteceu sem ler metade do código base.

78~

79## Três regras que evitam muito caos

80~

81Primeira regra: cada serviço deve ter `service.name`, ambiente e versão. Parece trivial, mas sem esses atributos um trace é muito menos útil. Quando uma implantação quebra alguma coisa, você deseja filtrar por versão em dois segundos.

82~

83Segunda regra: não coloque dados confidenciais nos atributos. E-mails, tokens, cargas inteiras e endereços não devem acabar em um back-end de observabilidade por acidente. Se você precisar identificar um usuário, considere IDs internos, hash ou campos menos confidenciais.

84~

85Terceira regra: preste atenção à cardinalidade. `user.id` como um atributo de trace pode fazer sentido. Como rótulo de métrica, pode destruir seus custos e desempenho.

86~

87## Métricas: poucas, mas boas

88~

89Eu começaria com métricas muito práticas:

90~

91- taxas, erros e duração das solicitações;

92- latência de dependências externas;

93- número de timeouts e novas tentativas;

94- profundidade das caudas;

95- duração do trabalho;

96- porcentagem de erros por versão.

97~

98O resto é adicionado quando necessário. Painéis cheios de gráficos que ninguém olha são móveis, não observabilidade.

99~

100## Logs: ainda úteis, mas vinculados

101~

102Os registros não desaparecem. Eles simplesmente se tornam muito mais úteis quando carregam `trace_id` e `span_id`. Portanto, você pode começar a partir de um log de erros e abrir o trace, ou começar a partir de um trace lento e ler apenas os logs produzidos nesse caminho.

103~

104Sem correlação, você está procurando agulhas. Com a correlação, pelo menos você sabe em qual gaveta procurar.

105~

106## A lista de verificação que eu usaria antes de dizer "estamos cobertos"

107~

108- O trace na verdade cruza vários serviços.

109- Os registros incluem `trace_id` e `span_id`.

110- O Collector está configurado com lotes e limites de memória.

111- Os erros são registrados em span.

112- Existe uma política de amostragem.

113- As métricas têm cardinalidade controlada.

114- Dados confidenciais são filtrados.

115- Os alertas começam a partir dos sintomas do usuário, não de gráficos aleatórios.

116~

117## Conclusão

118~

119OpenTelemetry não resolve problemas de produção por si só. Mas a maneira como você lida com eles muda. Em vez de adicionar logs às cegas, você começa a seguir o caminho real de uma solicitação.

120~

121Para mim o sinal de que está funcionando é simples: quando algo acontece, a equipe para de perguntar “para onde estamos olhando?” e começa a perguntar "por que essa peça está lenta?". É aí que a observabilidade se torna uma ferramenta, não uma coleção de painéis.

122~

123## Fontes

124~

125- [OpenTelemetry: Overview](https://opentelemetry.io/docs/specs/otel/overview/)

126- [OpenTelemetry Collector: Configuration](https://opentelemetry.io/docs/collector/configuration/)

127- [OpenTelemetry JavaScript: Node.js getting started](https://opentelemetry.io/docs/languages/js/getting-started/nodejs/)

128- [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/concepts/semantic-conventions/)

129~