|
| 1 | +--- |
| 2 | +title: Navegador |
| 3 | +aliases: [/docs/js/getting_started/browser] |
| 4 | +description: Aprenda como adicionar o OpenTelemetry à sua aplicação de navegador |
| 5 | +weight: 20 |
| 6 | +default_lang_commit: 1f6a173c26d1e194696ba77e95b6c3af40234952 |
| 7 | +--- |
| 8 | + |
| 9 | +{{% alert title="Aviso" color="warning" %}} |
| 10 | +{{% param notes.browser-instrumentation %}} {{% /alert %}} |
| 11 | + |
| 12 | +Embora este guia utilize o exemplo de aplicação apresentada abaixo, as etapas |
| 13 | +para instrumentar a sua própria aplicação devem ser similares. |
| 14 | + |
| 15 | +## Pré-requisitos {#prerequisites} |
| 16 | + |
| 17 | +Certifique-se de que você tenha instalado localmente: |
| 18 | + |
| 19 | +- [Node.js](https://nodejs.org/en/download/) |
| 20 | +- [TypeScript](https://www.typescriptlang.org/download), caso esteja utilizando |
| 21 | + TypeScript. |
| 22 | + |
| 23 | +## Exemplo de aplicação {#example-application} |
| 24 | + |
| 25 | +Este é um guia muito simples. Caso deseje visualizar exemplos mais complexos, |
| 26 | +consulte o repositório |
| 27 | +[examples/opentelemetry-web](https://github.com/open-telemetry/opentelemetry-js/tree/main/examples/opentelemetry-web). |
| 28 | + |
| 29 | +Copie o conteúdo a seguir em um arquivo em um diretório vazio e salve-o como |
| 30 | +`index.html`. |
| 31 | + |
| 32 | +```html |
| 33 | +<!doctype html> |
| 34 | +<html lang="en"> |
| 35 | + <head> |
| 36 | + <meta charset="utf-8" /> |
| 37 | + <title>Exemplo de Instrumentação ao Carregar Documento</title> |
| 38 | + <base href="/" /> |
| 39 | + <!-- |
| 40 | + https://www.w3.org/TR/trace-context/ |
| 41 | + Defina o `traceparent` no código do template HTML do servidor. Ele |
| 42 | + deve ser gerado dinamicamente pelo servidor para conter o ID do rastro |
| 43 | + da requisição do servidor, um ID de trecho pai que foi definido no trecho |
| 44 | + da requisição do servidor e as flags de rastro para indicar a decisão de |
| 45 | + amostragem do servidor (01 = amostrado, 00 = não amostrado). |
| 46 | + '{versão}-{IDDoRastro}-{IDDoTrecho}-{decisãoDeAmostragem}'' |
| 47 | + --> |
| 48 | + <meta |
| 49 | + name="traceparent" |
| 50 | + content="00-ab42124a3c573678d4d8b21ba52df3bf-d21f7bc17caa5aba-01" |
| 51 | + /> |
| 52 | + <meta name="viewport" content="width=device-width, initial-scale=1" /> |
| 53 | + </head> |
| 54 | + <body> |
| 55 | + Exemplo de utilização do Tracer Web com instrumentação do carregamento de |
| 56 | + documento com Exporter de Console e Exporter de Collector |
| 57 | + </body> |
| 58 | +</html> |
| 59 | +``` |
| 60 | + |
| 61 | +### Instalação {#installation} |
| 62 | + |
| 63 | +Para criar rastros no navegador, você precisará do |
| 64 | +`@opentelemetry/sdk-trace-web` e da instrumentação |
| 65 | +`@opentelemetry/instrumentation-document-load`: |
| 66 | + |
| 67 | +```shell |
| 68 | +npm init -y |
| 69 | +npm install @opentelemetry/api \ |
| 70 | + @opentelemetry/sdk-trace-web \ |
| 71 | + @opentelemetry/instrumentation-document-load \ |
| 72 | + @opentelemetry/context-zone |
| 73 | +``` |
| 74 | + |
| 75 | +### Inicialização e configuração {#initialization-and-configuration} |
| 76 | + |
| 77 | +Caso esteja escrevendo seu código em TypeScript, execute o seguinte comando: |
| 78 | + |
| 79 | +```shell |
| 80 | +tsc --init |
| 81 | +``` |
| 82 | + |
| 83 | +Em seguida, adicione o [parcel](https://parceljs.org/), que permitirá (entre |
| 84 | +outras coisas) que você trabalhe com TypeScript. |
| 85 | + |
| 86 | +```shell |
| 87 | +npm install --save-dev parcel |
| 88 | +``` |
| 89 | + |
| 90 | +Crie um arquivo de código vazio chamado `document-load` com a extensão `.ts` ou |
| 91 | +`.js`, conforme apropriado, com base na linguagem que você escolheu para |
| 92 | +escrever sua aplicação. Adicione o seguinte código ao seu HTML, logo antes da |
| 93 | +tag de fechamento `</body>`: |
| 94 | + |
| 95 | +{{< tabpane text=true >}} {{% tab TypeScript %}} |
| 96 | + |
| 97 | +```html |
| 98 | +<script type="module" src="document-load.ts"></script> |
| 99 | +``` |
| 100 | + |
| 101 | +{{% /tab %}} {{% tab JavaScript %}} |
| 102 | + |
| 103 | +```html |
| 104 | +<script type="module" src="document-load.js"></script> |
| 105 | +``` |
| 106 | + |
| 107 | +{{% /tab %}} {{< /tabpane >}} |
| 108 | + |
| 109 | +Adicionaremos o código para rastrear os tempos de carregamento do documento e |
| 110 | +relatar esses dados como trechos OpenTelemetry. |
| 111 | + |
| 112 | +### Criando um Tracer Provider {#creating-a-tracer-provider} |
| 113 | + |
| 114 | +Adicione o seguinte código ao arquivo `document-load.ts|js` para criar um Tracer |
| 115 | +Provider, que trará a instrumentação para rastrear o tempo de carregamento do |
| 116 | +documento: |
| 117 | + |
| 118 | +```js |
| 119 | +/* arquivo document-load.ts|js - este trecho do código é o mesmo para ambas as linguagens */ |
| 120 | +import { WebTracerProvider } from '@opentelemetry/sdk-trace-web'; |
| 121 | +import { DocumentLoadInstrumentation } from '@opentelemetry/instrumentation-document-load'; |
| 122 | +import { ZoneContextManager } from '@opentelemetry/context-zone'; |
| 123 | +import { registerInstrumentations } from '@opentelemetry/instrumentation'; |
| 124 | + |
| 125 | +const provider = new WebTracerProvider(); |
| 126 | + |
| 127 | +provider.register({ |
| 128 | + // Alterando o contextManager padrão para utilizar o ZoneContextManager - oferece suporte para operações assíncronas - opcional |
| 129 | + contextManager: new ZoneContextManager(), |
| 130 | +}); |
| 131 | + |
| 132 | +// Registrando instrumentações |
| 133 | +registerInstrumentations({ |
| 134 | + instrumentations: [new DocumentLoadInstrumentation()], |
| 135 | +}); |
| 136 | +``` |
| 137 | + |
| 138 | +Agora crie a aplicação com parcel: |
| 139 | + |
| 140 | +```shell |
| 141 | +npx parcel index.html |
| 142 | +``` |
| 143 | + |
| 144 | +e acesse o servidor web de desenvolvimento (por exemplo, em |
| 145 | +`http://localhost:1234`) para validar se o seu código funciona. |
| 146 | + |
| 147 | +Ainda não haverá saída de rastros, para isso precisamos adicionar um exportador. |
| 148 | + |
| 149 | +### Criando um Exporter {#creating-an-exporter} |
| 150 | + |
| 151 | +No exemplo a seguir, utilizaremos o `ConsoleSpanExporter` que exibe todos os |
| 152 | +trechos no console. |
| 153 | + |
| 154 | +Para visualizar e analisar seus rastros, você precisará exportá-los para um |
| 155 | +_backend_ de rastreamento. Siga [estas instruções](../../exporters) para |
| 156 | +configurar um _backend_ e um exportador. |
| 157 | + |
| 158 | +Você também pode utilizar o `BatchSpanProcessor` para exportar trechos em lotes |
| 159 | +de forma a utilizar os recursos mais eficientemente. |
| 160 | + |
| 161 | +Para exportar os rastros para o console, modifique o arquivo |
| 162 | +`document-load.ts|js` para que corresponda ao seguinte trecho de código: |
| 163 | + |
| 164 | +```js |
| 165 | +/* arquivo document-load.ts|js - o código é o mesmo para ambas as linguagens */ |
| 166 | +import { |
| 167 | + ConsoleSpanExporter, |
| 168 | + SimpleSpanProcessor, |
| 169 | +} from '@opentelemetry/sdk-trace-base'; |
| 170 | +import { WebTracerProvider } from '@opentelemetry/sdk-trace-web'; |
| 171 | +import { DocumentLoadInstrumentation } from '@opentelemetry/instrumentation-document-load'; |
| 172 | +import { ZoneContextManager } from '@opentelemetry/context-zone'; |
| 173 | +import { registerInstrumentations } from '@opentelemetry/instrumentation'; |
| 174 | + |
| 175 | +const provider = new WebTracerProvider({ |
| 176 | + spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())], |
| 177 | +}); |
| 178 | + |
| 179 | +provider.register({ |
| 180 | + // Alterando o contextManager padrão para utilizar o ZoneContextManager - oferece suporte para operações assíncronas - opcional |
| 181 | + contextManager: new ZoneContextManager(), |
| 182 | +}); |
| 183 | + |
| 184 | +// Registrando instrumentações |
| 185 | +registerInstrumentations({ |
| 186 | + instrumentations: [new DocumentLoadInstrumentation()], |
| 187 | +}); |
| 188 | +``` |
| 189 | + |
| 190 | +Agora, reconstrua sua aplicação e abra o navegador novamente. No console da |
| 191 | +barra de ferramentas do desenvolvedor, você deverá ver alguns rastros sendo |
| 192 | +exportados: |
| 193 | + |
| 194 | +```json |
| 195 | +{ |
| 196 | + "traceId": "ab42124a3c573678d4d8b21ba52df3bf", |
| 197 | + "parentId": "cfb565047957cb0d", |
| 198 | + "name": "documentFetch", |
| 199 | + "id": "5123fc802ffb5255", |
| 200 | + "kind": 0, |
| 201 | + "timestamp": 1606814247811266, |
| 202 | + "duration": 9390, |
| 203 | + "attributes": { |
| 204 | + "component": "document-load", |
| 205 | + "http.response_content_length": 905 |
| 206 | + }, |
| 207 | + "status": { |
| 208 | + "code": 0 |
| 209 | + }, |
| 210 | + "events": [ |
| 211 | + { |
| 212 | + "name": "fetchStart", |
| 213 | + "time": [1606814247, 811266158] |
| 214 | + }, |
| 215 | + { |
| 216 | + "name": "domainLookupStart", |
| 217 | + "time": [1606814247, 811266158] |
| 218 | + }, |
| 219 | + { |
| 220 | + "name": "domainLookupEnd", |
| 221 | + "time": [1606814247, 811266158] |
| 222 | + }, |
| 223 | + { |
| 224 | + "name": "connectStart", |
| 225 | + "time": [1606814247, 811266158] |
| 226 | + }, |
| 227 | + { |
| 228 | + "name": "connectEnd", |
| 229 | + "time": [1606814247, 811266158] |
| 230 | + }, |
| 231 | + { |
| 232 | + "name": "requestStart", |
| 233 | + "time": [1606814247, 819101158] |
| 234 | + }, |
| 235 | + { |
| 236 | + "name": "responseStart", |
| 237 | + "time": [1606814247, 819791158] |
| 238 | + }, |
| 239 | + { |
| 240 | + "name": "responseEnd", |
| 241 | + "time": [1606814247, 820656158] |
| 242 | + } |
| 243 | + ] |
| 244 | +} |
| 245 | +``` |
| 246 | + |
| 247 | +### Adicionar instrumentações {#add-instrumentations} |
| 248 | + |
| 249 | +Caso deseje instrumentar requisições Ajax, interações do usuário e outros, é |
| 250 | +possível registrar instrumentações adicionais para esses elementos: |
| 251 | + |
| 252 | +```javascript |
| 253 | +registerInstrumentations({ |
| 254 | + instrumentations: [ |
| 255 | + new UserInteractionInstrumentation(), |
| 256 | + new XMLHttpRequestInstrumentation(), |
| 257 | + ], |
| 258 | +}); |
| 259 | +``` |
| 260 | + |
| 261 | +## Pacotes Meta para Web {#meta-packages-for-web} |
| 262 | + |
| 263 | +Para aproveitar as instrumentações mais comuns em um único lugar, você pode |
| 264 | +simplesmente usar os |
| 265 | +[Pacotes Meta do OpenTelemetry para Web](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-web). |
0 commit comments