Skip to content

Commit 300313b

Browse files
vitorvascvitorvasc
authored
[pt] Localize content/en/docs/languages/js/libraries.md (#8406)
1 parent a8aca72 commit 300313b

File tree

3 files changed

+367
-0
lines changed

3 files changed

+367
-0
lines changed

‎content/pt/docs/languages/_includes/libraries-intro.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
default_lang_commit: 3574925e7c75e789f1405db04a285323679b0fd9
3+
---
4+
5+
Ao desenvolver uma aplicação, é possível utilizar bibliotecas e _frameworks_ de
6+
terceiros para acelerar seu trabalho. Caso você instrumente sua aplicação
7+
utilizando OpenTelemetry, talvez queira evitar gastar tempo adicional para
8+
adicionar manualmente rastros, logs e métricas às bibliotecas e _frameworks_ de
9+
terceiros que utiliza.
10+
11+
Muitas bibliotecas e _frameworks_ já oferecem suporte ao OpenTelemetry ou são
12+
compatíveis por meio da
13+
[instrumentação](/docs/concepts/instrumentation/libraries/), permitindo gerar
14+
dados de telemetria que podem ser exportados para um _backend_ de
15+
observabilidade.
16+
17+
Caso você esteja instrumentando uma aplicação ou serviço que utilize bibliotecas
18+
ou _frameworks_ de terceiros, siga estas instruções para aprender como usar
19+
bibliotecas instrumentadas nativamente e bibliotecas de instrumentação para as
20+
dependências do seu projeto.
21+
22+
## Usar bibliotecas com instrumentação nativa {#use-natively-instrumented-libraries}
23+
24+
Se uma biblioteca oferece suporte ao OpenTelemetry por padrão, é possível obter
25+
rastros, métricas e logs emitidos por essa biblioteca ao adicionar e configurar
26+
o SDK do OpenTelemetry na sua aplicação.
27+
28+
A biblioteca pode exigir alguma configuração adicional para sua instrumentação.
29+
Consulte a documentação dessa biblioteca para saber mais.

‎content/pt/docs/languages/_includes/native-lib-alert.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
default_lang_commit: 6eddc725571667e112a41aa7422bcd4c69764503
3+
---
4+
5+
{{ if $noIntegrations }}
6+
7+
{{% alert title="Colabore conosco!" color=secondary %}}
8+
9+
Até o momento, não temos conhecimento de nenhuma biblioteca {{ $name }} que
10+
possua integração com o OpenTelemetry de forma nativa. Se você souber de alguma,
11+
[avise-nos][let us know].
12+
13+
{{% /alert %}}
14+
15+
{{ end }}
16+
17+
{{ if not $noIntegrations }}
18+
19+
{{% alert color=info %}}
20+
21+
Caso saiba de alguma biblioteca {{ $name }} que possua integração com o
22+
OpenTelemetry de forma nativa, [avise-nos][let us know].
23+
24+
{{% /alert %}}
25+
26+
{{ end }}
27+
28+
[let us know]:
29+
https://github.com/open-telemetry/opentelemetry.io/issues/new/choose

‎content/pt/docs/languages/js/libraries.md‎

Lines changed: 309 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,309 @@
1+
---
2+
title: Usando bibliotecas de instrumentação
3+
linkTitle: Bibliotecas
4+
weight: 40
5+
default_lang_commit: 115933c1b9c643c8b6cf0d413a32061cd3a1b65f
6+
description: Como instrumentar bibliotecas das quais uma aplicação depende
7+
cSpell:ignore: metapackages metapacotes
8+
---
9+
10+
{{% docs/languages/libraries-intro "js" %}}
11+
12+
## Usando bibliotecas de instrumentação {#use-instrumentation-libraries}
13+
14+
Se uma biblioteca não vem com OpenTelemetry de forma nativa, é possível utilizar
15+
[bibliotecas de instrumentação](/docs/specs/otel/glossary/#instrumentation-library)
16+
para gerar dados de telemetria para uma biblioteca ou _framework_.
17+
18+
Por exemplo,
19+
[a biblioteca de instrumentação para Express](https://www.npmjs.com/package/@opentelemetry/instrumentation-express)
20+
irá criar automaticamente [trechos](/docs/concepts/signals/traces/#spans)
21+
baseados nas requisições HTTP de entrada.
22+
23+
### Configuração {#setup}
24+
25+
Cada biblioteca de instrumentação é um pacote NPM. Por exemplo, veja como
26+
instalar as bibliotecas
27+
[instrumentation-express](https://www.npmjs.com/package/@opentelemetry/instrumentation-express)
28+
e
29+
[instrumentation-http](https://www.npmjs.com/package/@opentelemetry/instrumentation-http)
30+
para instrumentar tráfego HTTP de entrada e saída:
31+
32+
```sh
33+
npm install --save @opentelemetry/instrumentation-http @opentelemetry/instrumentation-express
34+
```
35+
36+
O OpenTelemetry JavaScript também define metapacotes (_metapackages_)
37+
[auto-instrumentation-node](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-node)
38+
e
39+
[auto-instrumentation-web](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-web),
40+
que agrupam todas as bibliotecas de instrumentação baseadas em Node.js ou web em
41+
um único pacote. É uma maneira conveniente de adicionar telemetria gerada
42+
automaticamente para todas as suas bibliotecas com esforço mínimo:
43+
44+
{{< tabpane text=true >}}
45+
46+
{{% tab Node.js %}}
47+
48+
```shell
49+
npm install --save @opentelemetry/auto-instrumentations-node
50+
```
51+
52+
{{% /tab %}}
53+
54+
{{% tab Browser %}}
55+
56+
```shell
57+
npm install --save @opentelemetry/auto-instrumentations-web
58+
```
59+
60+
{{% /tab %}} {{< /tabpane >}}
61+
62+
Note que usar esses metapacotes aumenta o tamanho do seu grafo de dependências.
63+
Utilize bibliotecas de instrumentação individuais caso você saiba exatamente
64+
quais precisa.
65+
66+
### Registro {#registration}
67+
68+
Após instalar as bibliotecas de instrumentação necessárias, registre-as no SDK
69+
do OpenTelemetry para Node.js. Se você seguiu os
70+
[Primeiros Passos](/docs/languages/js/getting-started/nodejs/), você já utiliza
71+
os metapacotes. Se você seguiu as instruções
72+
[para inicializar o SDK com instrumentação manual](/docs/languages/js/instrumentation/#initialize-tracing),
73+
atualize seu `instrumentation.ts` (ou `instrumentation.js`) da seguinte forma:
74+
75+
{{< tabpane text=true >}}
76+
77+
{{% tab TypeScript %}}
78+
79+
```typescript
80+
/*instrumentation.ts*/
81+
...
82+
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
83+
84+
const sdk = new NodeSDK({
85+
...
86+
// Registra todos os pacotes de instrumentação
87+
instrumentations: [getNodeAutoInstrumentations()]
88+
});
89+
90+
sdk.start()
91+
```
92+
93+
{{% /tab %}}
94+
95+
{{% tab JavaScript %}}
96+
97+
```javascript
98+
/*instrumentation.js*/
99+
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
100+
101+
const sdk = new NodeSDK({
102+
...
103+
// Registra todos os pacotes de instrumentação
104+
instrumentations: [getNodeAutoInstrumentations()]
105+
});
106+
```
107+
108+
{{% /tab %}}
109+
110+
{{< /tabpane >}}
111+
112+
Para desabilitar bibliotecas de instrumentação individuais, aplique a seguinte
113+
alteração:
114+
115+
{{< tabpane text=true >}}
116+
117+
{{% tab TypeScript %}}
118+
119+
```typescript
120+
/*instrumentation.ts*/
121+
...
122+
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
123+
124+
const sdk = new NodeSDK({
125+
...
126+
// Registra todos os pacotes de instrumentação
127+
instrumentations: [
128+
getNodeAutoInstrumentations({
129+
'@opentelemetry/instrumentation-fs': {
130+
enabled: false,
131+
},
132+
}),
133+
],
134+
});
135+
136+
sdk.start()
137+
```
138+
139+
{{% /tab %}}
140+
141+
{{% tab JavaScript %}}
142+
143+
```javascript
144+
/*instrumentation.js*/
145+
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
146+
147+
const sdk = new NodeSDK({
148+
...
149+
// Registra todos os pacotes de instrumentação
150+
instrumentations: [
151+
getNodeAutoInstrumentations({
152+
'@opentelemetry/instrumentation-fs': {
153+
enabled: false,
154+
},
155+
}),
156+
],
157+
});
158+
```
159+
160+
{{% /tab %}}
161+
162+
{{< /tabpane >}}
163+
164+
Para carregar apenas bibliotecas de instrumentação individuais, substitua
165+
`[getNodeAutoInstrumentations()]` pela lista daquelas que você precisa:
166+
167+
{{< tabpane text=true >}}
168+
169+
{{% tab TypeScript %}}
170+
171+
```typescript
172+
/*instrumentation.ts*/
173+
...
174+
import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
175+
import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";
176+
177+
const sdk = new NodeSDK({
178+
...
179+
instrumentations: [
180+
// A instrumentação Express espera que a camada HTTP esteja instrumentada
181+
new HttpInstrumentation(),
182+
new ExpressInstrumentation(),
183+
]
184+
});
185+
186+
sdk.start()
187+
```
188+
189+
{{% /tab %}} {{% tab JavaScript %}}
190+
191+
```javascript
192+
/*instrumentation.js*/
193+
const { HttpInstrumentation } = require("@opentelemetry/instrumentation-http");
194+
const { ExpressInstrumentation } = require("@opentelemetry/instrumentation-express");
195+
196+
const sdk = new NodeSDK({
197+
...
198+
instrumentations: [
199+
// A instrumentação Express espera que a camada HTTP esteja instrumentada
200+
new HttpInstrumentation(),
201+
new ExpressInstrumentation(),
202+
]
203+
});
204+
```
205+
206+
{{% /tab %}}
207+
208+
{{< /tabpane >}}
209+
210+
### Configuração {#configuration}
211+
212+
Algumas bibliotecas de instrumentação oferecem opções de configuração
213+
adicionais.
214+
215+
Por exemplo,
216+
[a instrumentação Express](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/packages/instrumentation-express#express-instrumentation-options)
217+
oferece formas de ignorar _middlewares_ especificados ou enriquecer trechos
218+
criados automaticamente com um _hook_ de requisição:
219+
220+
{{< tabpane text=true >}}
221+
222+
{{% tab TypeScript %}}
223+
224+
```typescript
225+
import { Span } from '@opentelemetry/api';
226+
import {
227+
SEMATTRS_HTTP_METHOD,
228+
SEMATTRS_HTTP_URL,
229+
} from '@opentelemetry/semantic-conventions';
230+
import {
231+
ExpressInstrumentation,
232+
ExpressLayerType,
233+
ExpressRequestInfo,
234+
} from '@opentelemetry/instrumentation-express';
235+
236+
const expressInstrumentation = new ExpressInstrumentation({
237+
requestHook: function (span: Span, info: ExpressRequestInfo) {
238+
if (info.layerType === ExpressLayerType.REQUEST_HANDLER) {
239+
span.setAttribute(SEMATTRS_HTTP_METHOD, info.request.method);
240+
span.setAttribute(SEMATTRS_HTTP_URL, info.request.baseUrl);
241+
}
242+
},
243+
});
244+
```
245+
246+
{{% /tab %}}
247+
248+
{{% tab JavaScript %}}
249+
250+
```javascript
251+
/*instrumentation.js*/
252+
const {
253+
SEMATTRS_HTTP_METHOD,
254+
SEMATTRS_HTTP_URL,
255+
} = require('@opentelemetry/semantic-conventions');
256+
const {
257+
ExpressInstrumentation,
258+
ExpressLayerType,
259+
} = require('@opentelemetry/instrumentation-express');
260+
261+
const expressInstrumentation = new ExpressInstrumentation({
262+
requestHook: function (span, info) {
263+
if (info.layerType === ExpressLayerType.REQUEST_HANDLER) {
264+
span.setAttribute(SEMATTRS_HTTP_METHOD, info.request.method);
265+
span.setAttribute(SEMATTRS_HTTP_URL, info.request.baseUrl);
266+
}
267+
},
268+
});
269+
```
270+
271+
{{% /tab %}}
272+
273+
{{< /tabpane >}}
274+
275+
Consulte a documentação de cada biblioteca de instrumentação para opções
276+
avançadas.
277+
278+
### Bibliotecas de instrumentação disponíveis {#available-instrumentation-libraries}
279+
280+
É possível encontrar a lista de instrumentações disponíveis no
281+
[registro](/ecosystem/registry/?language=js&component=instrumentation).
282+
283+
## Instrumentar uma biblioteca nativamente {#instrument-a-library-natively}
284+
285+
Caso queira adicionar instrumentação nativa à sua biblioteca, consulte a
286+
seguinte documentação:
287+
288+
- A página de conceito [Bibliotecas](/docs/concepts/instrumentation/libraries/)
289+
fornece informações úteis sobre quando instrumentar e o que instrumentar.
290+
- A página de [instrumentação manual](/docs/languages/js/instrumentation/)
291+
fornece exemplos de código necessários para criar rastros, métricas e logs
292+
para sua biblioteca.
293+
- O
294+
[Guia de Implementação de Instrumentação](https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/GUIDELINES.md)
295+
para Node.js e navegador contém boas práticas específicas de JavaScript para
296+
criar instrumentação de bibliotecas.
297+
298+
## Criar uma biblioteca de instrumentação {#create-an-instrumentation-library}
299+
300+
Embora ter observabilidade pronta para uso em uma aplicação seja a forma
301+
preferida, isso nem sempre é possível ou desejado. Nesses casos, você pode criar
302+
uma biblioteca de instrumentação, que irá injetar chamadas de instrumentação
303+
utilizando mecanismos como empacotamento de _interfaces_, assinatura de funções
304+
de retorno (_callbacks_) específicos da biblioteca ou tradução de telemetria
305+
existente para o modelo do OpenTelemetry.
306+
307+
Para criar uma biblioteca desse tipo, siga o
308+
[Guia de Implementação de Instrumentação](https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/GUIDELINES.md)
309+
para Node.js e navegador.

0 commit comments

Comments
 (0)