> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Guia de migração

<Note>
  🛟 Não hesite em [entrar em contato conosco](mailto:support@appsignal.com) se encontrar
  problemas ao atualizar o pacote AppSignal para Node.js da sua aplicação.
  Estamos aqui para ajudar!
</Note>

Esta documentação lista as mudanças entre os lançamentos 2.x e 3.x do pacote Node.js do AppSignal.

Se você estiver atualizando da 2.x para a 3.x, será necessário modificar sua integração para que funcione corretamente.

Se encontrar problemas durante a atualização da sua aplicação, certifique-se de [entrar em contato conosco](mailto:support@appsignal.com) para obter suporte.

## Instalando a 3.x

Para instalar o AppSignal para Node.js 3.x, execute o seguinte comando no diretório raiz da sua aplicação.

#### npm

<CodeGroup>
  ```bash Bash theme={null}
  npm install @appsignal/nodejs
  ```
</CodeGroup>

## Cliente AppSignal

Ao atualizar da 2.x para a 3.x, você precisa mudar a forma como a sua aplicação inicializa e acessa o cliente AppSignal.

### Inicializar o cliente AppSignal

Para inicializar o cliente AppSignal e exportá-lo, você precisará criar um novo arquivo `appsignal.cjs`, como no exemplo abaixo:

<CodeGroup>
  ```javascript Node.js theme={null}
  // appsignal.cjs

  const { Appsignal } = require("@appsignal/nodejs");

  const appsignal = new Appsignal({
    active: true,
    name: "Your app name",
  });
  ```
</CodeGroup>

Você precisará exigir (`--require ./appsignal.cjs`) o arquivo `appsignal.cjs` ao iniciar sua aplicação. Por exemplo, no arquivo `package.json` da sua aplicação, como no exemplo abaixo:

#### Javascript

<CodeGroup>
  ```json JSON theme={null}
  "scripts": {
    "server": "node --require ./appsignal.cjs index.js"
  }
  ```
</CodeGroup>

### Acessar o cliente AppSignal

Na 3.x, o cliente AppSignal é acessado a partir do objeto exportado globalmente `Appsignal.client`. Os exemplos abaixo mostram como fazer isso no contexto de um [contador de métricas personalizadas](/metrics/custom#counter).

#### 2.x

<CodeGroup>
  ```javascript Node.js theme={null}
  import { appsignal } from "./appsignal";
  // or: const appsignal = new Appsignal({...});

  const meter = appsignal.metrics();
  meter.incrementCounter("slow_queries", 1);
  ```
</CodeGroup>

#### 3.x

<CodeGroup>
  ```javascript Node.js theme={null}
  import { Appsignal } from "@appsignal/nodejs";
  // or: const { Appsignal } = require("@appsignal/nodejs");

  const meter = Appsignal.client.metrics();
  meter.incrementCounter("slow_queries", 1);
  ```
</CodeGroup>

## Integrações

<Tip>
  Express e Next.js requerem um [tratador de
  erros](/nodejs/3.x/integrations/express#error-handler).
</Tip>

O AppSignal para Node.js 3.x suporta todas as integrações da 2.x prontas para uso. Isso significa que os pacotes de cada integração não precisam mais ser instalados.

Ao migrar da 2.x para a 3.x, você precisará remover quaisquer pacotes de integração do AppSignal instalados em sua aplicação.

### Desinstalar integrações

<Warning>
  As integrações 2.x não são compatíveis com a integração Node.js 3.x. Você
  deve seguir as etapas de migração descritas abaixo para usar as integrações do Node.js.
</Warning>

Para aproveitar o suporte pronto para uso das integrações do AppSignal para Node.js 3.x, primeiro você precisará "desfazer" as instalações de integração que eram necessárias na versão 2.x.

#### Remover código dependente do pacote AppSignal

<Tip>
  Os exemplos abaixo são ilustrativos e baseados na documentação das integrações
  do AppSignal 2.x e 3.x. O código em sua aplicação pode diferir dos
  exemplos desta documentação.
</Tip>

* [Apollo Server](#remove-apollo-server-integration)
* [Express](#remove-express-integration)
* [Koa.js](#remove-koajs-integration)
* [Next.js](#remove-nextjs-integration)

**Não esqueça de [remover/desinstalar o pacote de integração do AppSignal](#remove-integration-package)**.

### Remover integração do Apollo Server

<Warning>
  O pacote 2.x `@appsignal/apollo-server` não é compatível com a integração
  Node.js 3.x. Você deve seguir as etapas de migração descritas abaixo se
  desejar usar o Apollo Server com nossa integração 3.x.
</Warning>

Remova a inicialização 2.x do pacote e plugin Appsignal Apollo Server da sua aplicação, e substitua-a pelas instruções de instalação 3.x.

Sua aplicação Apollo será instrumentada automaticamente.

#### 2.x

<CodeGroup>
  ```javascript Node.js theme={null}
  import { createApolloPlugin } from "@appsignal/apollo-server";
  import { ApolloServer, gql } from "apollo-server-express";
  // or: const { createApolloPlugin } = require("@appsignal/apollo-server");
  // or: const { ApolloServer, gql } = require("apollo-server-express");

  const server = new ApolloServer({
    /* ... */
    plugins: [createApolloPlugin(appsignal)],
  });
  ```
</CodeGroup>

#### 3.x

O Apollo Server é instrumentado automaticamente pelo pacote AppSignal para Node.js.

[Leia a documentação da integração GraphQL 3.x](/nodejs/3.x/integrations/graphql)

Depois de modificar o código da sua integração, você precisa [remover o pacote AppSignal Apollo](#remove-apollo-server-integration) da sua aplicação.

### Remover integração do Express

<Warning>
  O pacote 2.x `@appsignal/express` não é compatível com a integração Node.js
  3.x. Você deve seguir as etapas de migração descritas abaixo se desejar
  usar o express com nossa integração 3.x.
</Warning>

Remova a inicialização 2.x do pacote e middleware AppSignal Express da sua aplicação, e substitua-a pelas instruções de instalação 3.x.

#### 2.x

<CodeGroup>
  ```javascript Node.js theme={null}
  import express from "express";
  // or: const express = require("express");

  const {
    expressMiddleware,
    expressErrorHandler,
  } = require("@appsignal/express");
  // your app code goes here

  // add this after all other express middleware, but before any routes
  app.use(expressMiddleware(appsignal));

  // add this after all routes, but before any other error handlers
  app.use(expressErrorHandler(appsignal));
  ```
</CodeGroup>

#### 3.x

<CodeGroup>
  ```javascript Node.js theme={null}
  import { expressErrorHandler } from "@appsignal/nodejs";
  // or: const { expressErrorHandler } = require("@appsignal/nodejs");

  const app = express();
  // your app code goes here

  // add this after all routes, but before any other error handlers
  app.use(expressErrorHandler());
  ```
</CodeGroup>

[Leia a documentação da integração Express 3.x](/nodejs/3.x/integrations/express)

Depois de modificar o código da sua integração, você precisa [remover o pacote Appsignal Express](#remove-express-integration) da sua aplicação.

### Remover integração do Koa.js

<Warning>
  O pacote 2.x `@appsignal/koa` não é compatível com a integração Node.js
  3.x. Você deve seguir as etapas de migração descritas abaixo se desejar
  usar o Koa.js com nossa integração 3.x.
</Warning>

Remova a inicialização 2.x do pacote e instrumentação Appsignal Koa da sua aplicação.

#### 2.x

<CodeGroup>
  ```javascript Node.js theme={null}
  import appsignalKoa from "@appsignal/koa";
  // or: const appsignalKoa = require("@appsignal/koa");
  appsignal.instrument(appsignalKoa);
  ```
</CodeGroup>

#### 3.x

O Koa.js é instrumentado automaticamente pelo pacote AppSignal para Node.js.

[Leia a documentação da integração Koa.js 3.x](/nodejs/3.x/integrations/koajs)

Depois de modificar o código da sua integração, você precisa [remover o pacote Koa.js](#remove-koajs-integration) da sua aplicação.

### Remover integração do Next.js

<Warning>
  O pacote 2.x `@appsignal/nextjs` não é compatível com a integração Node.js
  3.x. Você deve seguir as etapas de migração descritas abaixo se desejar
  usar o Next.js com nossa integração 3.x.
</Warning>

O recurso "Web Vitals Reporting" foi descontinuado e não está mais disponível no AppSignal para Node.js 3.x.

#### 2.x

<CodeGroup>
  ```javascript Node.js theme={null}
  import { getRequestHandler } from "@appsignal/nextjs";
  // or: const { getRequestHandler } = require("@appsignal/nextjs");
  ```
</CodeGroup>

#### 3.x

O Next.js é instrumentado automaticamente pelo pacote AppSignal para Node.js.

[Leia a documentação da integração Next.js 3.x](/nodejs/3.x/integrations/nextjs)

### Remover pacote de integração

Depois que os imports e o código dependente desses imports forem removidos, você precisa desinstalar o pacote de integração.

Isso pode ser feito executando `npm uninstall`, como no exemplo abaixo.

```bash Bash theme={null}
npm uninstall @appsignal/express
```

Os comandos `npm uninstall` removerão as dependências de pacotes e atualizarão os arquivos `package.json` da sua aplicação e o `package-lock.json` do npm.

Substitua `@appsignal/express` no exemplo acima pelo nome do pacote de integração que você está removendo.

#### Nomes dos pacotes de integração do AppSignal

| Integração    | Nome do pacote             |
| ------------- | -------------------------- |
| Apollo Server | `@appsignal/apollo-server` |
| Express       | `@appsignal/express`       |
| Koa.js        | `@appsignal/koa`           |
| Next.js       | `@appsignal/nextjs`        |

## O objeto tracer

Não há mais um objeto tracer personalizado do AppSignal. O OpenTelemetry expõe um tracer provider que permite criar novos spans.

#### 2.x:

<CodeGroup>
  ```javascript Node.js theme={null}
  const tracer = appsignal.tracer();
  ```
</CodeGroup>

#### 3.x:

<CodeGroup>
  ```javascript Node.js theme={null}
  import { trace } from "@opentelemetry/api";
  // or: const { trace } = require("@opentelemetry/api");

  const tracer = trace.getTracer("my-interesting-app");
  ```
</CodeGroup>

[Leia mais sobre tracers na documentação de instrumentação 3.x.](/nodejs/3.x/instrumentation/instrumentation)

## Spans

Não há mais um objeto span personalizado do AppSignal. As funções do tracer do AppSignal, como `rootSpan()`, `createSpan()`, `currentSpan()` e `withSpan()`, não estão mais disponíveis.

Os spans devem ser criados chamando o método `startActiveSpan` em um objeto tracer. Novos spans são automaticamente filhos do span no qual foram criados.

#### 2.x:

<CodeGroup>
  ```javascript Node.js theme={null}
  tracer.withSpan(tracer.createSpan(), async (span) => {
    span.setName("your span's name");
    // logic to trace here
  });
  ```
</CodeGroup>

#### 3.x:

<CodeGroup>
  ```javascript Node.js theme={null}
  tracer.startActiveSpan("your span's name", async (span) => {
    /// logic to trace here
    span.end();
  });
  ```
</CodeGroup>

[Leia mais sobre spans na documentação de instrumentação 3.x.](/nodejs/3.x/instrumentation/instrumentation)

### Helpers de atributos de span

As funções auxiliares usadas para definir atributos de span também mudaram.

`setSQL` foi substituído por `setBody`, `set` foi renomeado para `setTag`, e funções auxiliares adicionais foram adicionadas. `setName` foi removida, pois os spans devem receber um nome quando são criados.

#### 2.x

<CodeGroup>
  ```javascript Node.js theme={null}
  const span = tracer.currentSpan();

  span.setCategory("query.sql");
  span.setSQL("SELECT * FROM users");
  ```
</CodeGroup>

#### 3.x

<CodeGroup>
  ```javascript JavaScript theme={null}
  setCategory("query.sql");
  setSQL("SELECT * FROM users");
  ```
</CodeGroup>

[Leia mais sobre os helpers de atributos de span na documentação de instrumentação 3.x.](/nodejs/3.x/instrumentation/instrumentation#helpers)

## Tratamento de exceções

Objetos tracer e span não são mais necessários ao usar `setError()` e `sendError()`.

#### 2.x

<CodeGroup>
  ```javascript Node.js theme={null}
  tracer.setError(err);

  tracer.sendError(err, (span) => {
    span.setName("daily.task");
    span.set("user_id", user_id);
  });
  ```
</CodeGroup>

#### 3.x

Em `sendError()`, [helpers](/nodejs/3.x/instrumentation/instrumentation#helpers) podem ser usados para adicionar dados adicionais ao span de erro.

<CodeGroup>
  ```javascript Node.js theme={null}
  import { setError, sendError } from "@appsignal/nodejs";
  // or: const { setError, sendError } = require("@appsignal/nodejs");

  setError(err);

  sendError(err, () => {
    setTag("user_id", user_id);
  });
  ```
</CodeGroup>

[Leia mais sobre tratamento de exceções na documentação de tratamento de exceções 3.x](/nodejs/3.x/instrumentation/exception-handling)