Quando ocorre um erro JavaScript em produção, o stack trace aponta para seu bundle minificado (main.a8f42b.js:1:42819). Isso é inútil para depuração. Source maps são os arquivos JSON que seu bundler emite, indicando como traduzir aqueles números de linha/coluna de volta para seu código-fonte original.
O rastreamento de erros — e source maps com ele — está disponível em planos Pro e acima.
Como source maps funcionam no Zenovay
- Seu build gera um bundle (por ex.
main.a8f42b.js) e um source map correspondente (main.a8f42b.js.map). - Você faz upload do source map para o Zenovay através da API de rastreamento de erros.
- Quando um erro chega, o tracker o compara com seus maps enviados usando o arquivo de bundle e o
releaseque você enviou. - O dashboard exibe o arquivo original, linha, coluna e um trecho de código.
Os source maps são armazenados contra um identificador de release — pode ser um SHA de Git, uma tag semver ou qualquer string que você definir. Se o release do erro não bater com um map enviado, você verá a linha minificada no dashboard.
Enviando source maps
Os source maps são enviados através da API de rastreamento de erros. O endpoint aceita um body JSON:
POST https://api.zenovay.com/api/errors/{websiteId}/sourcemap
| Campo | Obrigatório | Descrição |
|---|---|---|
fileName | sim | O nome sob o qual o map deve ser armazenado (p. ex. main.js) |
fileUrl | sim | A URL pública do bundle ao qual o map pertence |
release | recomendado | O identificador de release ao qual este map se aplica (omitir = armazenar sob default) |
mapContent | recomendado | O conteúdo do arquivo .map |
mapUrl | opcional | Uma URL de onde o map pode ser obtido, em vez de incorporar mapContent |
Estes endpoints requerem uma sessão Zenovay autenticada — passe seu token de acesso ao dashboard como um token Bearer (o token de curta duração que seu navegador usa quando você está conectado a app.zenovay.com). Eles não são acessíveis com uma chave API REST zv_*.
curl -X POST "https://api.zenovay.com/api/errors/{websiteId}/sourcemap" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d @- <<'JSON'
{
"fileName": "main.js",
"fileUrl": "https://example.com/static/main.js",
"release": "v2.4.1",
"mapContent": "<contents of main.js.map>"
}
JSON
Para ver o que já foi enviado para um site, liste seus maps:
GET https://api.zenovay.com/api/errors/{websiteId}/sourcemaps — adicione ?release=v2.4.1 para filtrar uma versão específica.
Execute o upload logo após cada build de produção para que cada versão seja entregue com maps, e verifique o status da resposta para que um upload falhado seja detectado em vez de ser silenciosamente ignorado. Note que o token de acesso é de curta duração, então ele precisa estar fresco cada vez que você faz o upload — um token de sessão capturado do dashboard não permanecerá válido por muito tempo.
Sobre o identificador de release
O campo release é o elo entre um erro capturado e um map enviado. Os erros são armazenados com o valor release sob o qual foram reportados, e um map é acoplado a um erro quando ambos compartilham o mesmo release.
Se você quiser que os erros estejam marcados com uma versão no dashboard, sua aplicação precisa relatar essa versão com cada erro que envia. Envie maps sob o mesmo identificador e os dois se alinham.
Verificando que está funcionando
- Envie um map e dispare um erro conhecido em produção.
- Abra o dashboard de seu site, vá para a aba Errors e abra o erro.
- A seção de stack trace deve exibir seu caminho de arquivo original (por ex.
src/components/Checkout.tsx:42) e uma breve prévia de código.
Se ainda exibir a linha minificada, verifique:
- O release sob o qual o erro foi reportado corresponde ao release sob o qual você enviou o map.
- A
fileUrlenviada corresponde ao bundle do qual o erro veio. - O arquivo
.mapnão está truncado (um upload parcial pode deixá-lo sem um map utilizável).
Privacidade
Os source maps contêm todo o seu código-fonte original. Eles são armazenados de forma privada, restritos ao seu site e nunca são servidos publicamente.