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

spinny:~/writing $ less 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

:OpenTelemetry em produção: pare de depurar no escurolines 1-129 (END) — press 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:

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?

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ã.

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

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

24```text

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

26```

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.

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.

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

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.

36```bash

37npm install @opentelemetry/sdk-node \

38 @opentelemetry/auto-instrumentations-node \

39 @opentelemetry/exporter-trace-otlp-http

40```

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

44```typescript

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

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

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

49const sdk = new NodeSDK({

50 traceExporter: new OTLPTraceExporter({

51 url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,

52 }),

53 instrumentations: [getNodeAutoInstrumentations()],

54});

56sdk.start();

57```

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.

61```typescript

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

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```

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.

79## Três regras que evitam muito caos

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.

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.

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.

87## Métricas: poucas, mas boas

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

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.

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

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