Guia de migração - AppSignal Documentation

🛟 Não hesite em entrar em contato conosco se encontrar problemas ao atualizar o pacote AppSignal para Node.js da sua aplicação. Estamos aqui para ajudar!

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

npm install @appsignal/nodejs

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:

// appsignal.cjs

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

const appsignal = new Appsignal({
  active: true,
  name: "Your app name",
});

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

"scripts": {
  "server": "node --require ./appsignal.cjs index.js"
}

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.

2.x

import { appsignal } from "./appsignal";
// or: const appsignal = new Appsignal({...});

const meter = appsignal.metrics();
meter.incrementCounter("slow_queries", 1);

3.x

import { Appsignal } from "@appsignal/nodejs";
// or: const { Appsignal } = require("@appsignal/nodejs");

const meter = Appsignal.client.metrics();
meter.incrementCounter("slow_queries", 1);

Integrações

Express e Next.js requerem um tratador de erros.

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

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.

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

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.

Apollo Server
Express
Koa.js
Next.js

Não esqueça de remover/desinstalar o pacote de integração do AppSignal.

Remover integração do Apollo Server

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.

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

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)],
});

3.x

O Apollo Server é instrumentado automaticamente pelo pacote AppSignal para Node.js. Leia a documentação da integração GraphQL 3.x Depois de modificar o código da sua integração, você precisa remover o pacote AppSignal Apollo da sua aplicação.

Remover integração do Express

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.

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

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));

3.x

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());

Leia a documentação da integração Express 3.x Depois de modificar o código da sua integração, você precisa remover o pacote Appsignal Express da sua aplicação.

Remover integração do Koa.js

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.

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

2.x

import appsignalKoa from "@appsignal/koa";
// or: const appsignalKoa = require("@appsignal/koa");
appsignal.instrument(appsignalKoa);

3.x

O Koa.js é instrumentado automaticamente pelo pacote AppSignal para Node.js. Leia a documentação da integração Koa.js 3.x Depois de modificar o código da sua integração, você precisa remover o pacote Koa.js da sua aplicação.

Remover integração do Next.js

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.

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

2.x

import { getRequestHandler } from "@appsignal/nextjs";
// or: const { getRequestHandler } = require("@appsignal/nextjs");

3.x

O Next.js é instrumentado automaticamente pelo pacote AppSignal para Node.js. Leia a documentação da integração Next.js 3.x

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

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:

const tracer = appsignal.tracer();

3.x:

import { trace } from "@opentelemetry/api";
// or: const { trace } = require("@opentelemetry/api");

const tracer = trace.getTracer("my-interesting-app");

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:

tracer.withSpan(tracer.createSpan(), async (span) => {
  span.setName("your span's name");
  // logic to trace here
});

3.x:

tracer.startActiveSpan("your span's name", async (span) => {
  /// logic to trace here
  span.end();
});

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

const span = tracer.currentSpan();

span.setCategory("query.sql");
span.setSQL("SELECT * FROM users");

3.x

setCategory("query.sql");
setSQL("SELECT * FROM users");

Tratamento de exceções

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

2.x

tracer.setError(err);

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

3.x

Em sendError(), helpers podem ser usados para adicionar dados adicionais ao span de erro.

import { setError, sendError } from "@appsignal/nodejs";
// or: const { setError, sendError } = require("@appsignal/nodejs");

setError(err);

sendError(err, () => {
  setTag("user_id", user_id);
});

​Instalando a 3.x

​npm

​Cliente AppSignal

​Inicializar o cliente AppSignal

​Javascript

​Acessar o cliente AppSignal

​2.x

​3.x

​Integrações

​Desinstalar integrações

​Remover código dependente do pacote AppSignal

​Remover integração do Apollo Server

​2.x

​3.x

​Remover integração do Express

​2.x

​3.x

​Remover integração do Koa.js

​2.x

​3.x

​Remover integração do Next.js

​2.x

​3.x

​Remover pacote de integração

​Nomes dos pacotes de integração do AppSignal

​O objeto tracer

​2.x:

​3.x:

​Spans

​2.x:

​3.x:

​Helpers de atributos de span

​2.x

​3.x

​Tratamento de exceções

​2.x

​3.x

Instalando a 3.x

npm

Cliente AppSignal

Inicializar o cliente AppSignal

Javascript

Acessar o cliente AppSignal

2.x

3.x

Integrações

Desinstalar integrações

Remover código dependente do pacote AppSignal

Remover integração do Apollo Server

2.x

3.x

Remover integração do Express

2.x

3.x

Remover integração do Koa.js

2.x

3.x

Remover integração do Next.js

2.x

3.x

Remover pacote de integração

Nomes dos pacotes de integração do AppSignal

O objeto tracer

2.x:

3.x:

Spans

2.x:

3.x:

Helpers de atributos de span

2.x

3.x

Tratamento de exceções

2.x

3.x