🛟 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! 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",
});
--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
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.
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.
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.
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.
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());
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.
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.
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.
npm uninstall @appsignal/express
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);
});
