Configuration
Most apps only need an API key. See where Vigilon gets each setting from, and how to override it.
Where settings come from
Vigilon works out each setting when your app starts, and prints the result in the Vigilon started: line. For each setting it checks the sources below from left to right and uses the first value it finds. Empty values are skipped.
API key (required): VIGILON_API_KEY.
Service name (required): VIGILON_SERVICE_NAME, then OTEL_SERVICE_NAME, then npm_package_name, then AWS_LAMBDA_FUNCTION_NAME, then the name in your package.json.
Environment (required): VIGILON_ENVIRONMENT, then ENVIRONMENT, then ENV, then NODE_ENV.
Service version (recommended): VIGILON_SERVICE_VERSION, then npm_package_version, then the version in your package.json.
You do not set npm_package_name or npm_package_version yourself. npm, pnpm, and yarn set them when you start your app through a script such as npm start, using the package.json that owns the script. Lambda sets AWS_LAMBDA_FUNCTION_NAME to your function's name.
If the API key, service name, or environment cannot be found, your app stops at startup with a message that names what is missing and which variable to set.
Service name
How you start your app decides which package.json the name comes from.
Started through a script, such as npm start: the name comes from the package.json that owns the script. In a monorepo, a script at the repository root that starts an app in packages/api reports the root package's name, not the app's.
Started with a plain node command: Vigilon uses the package.json closest to your app's entry file. node packages/api/dist/server.js picks up packages/api/package.json, not the one at the repository root.
Scoped names are kept as they are: @acme/api stays @acme/api. If the result is not what you want, set VIGILON_SERVICE_NAME. It always wins.
Service version
The version tells Vigilon when a new deployment went out. If you do not update the version in package.json on every deploy, set VIGILON_SERVICE_VERSION from your deploy pipeline instead, for example to the commit SHA:
export VIGILON_SERVICE_VERSION="$GITHUB_SHA"
Vigilon logs a warning at startup when it cannot find a version.
Optional settings
None of these are needed to get started:
# Turn Vigilon off, for example on your own machine
export VIGILON_DISABLED=1
# Print detailed logs while troubleshooting
export VIGILON_DEBUG=1
# Leave out extra routes
export VIGILON_EXCLUDED_URLS="/metrics,/internal/status"
# Send data to a different address
export VIGILON_OTEL_ENDPOINT="http://localhost:4318"
VIGILON_DISABLED lets you keep the --import flag in your start script and still run the app without an API key. Vigilon logs one notice and collects nothing. 1, true, and yes all work.
VIGILON_OTEL_ENDPOINT is a base address; Vigilon adds /v1/traces to it. The default is https://ingest.vigilon.io, and most apps never change it.
Start Vigilon from code
The --import flag is the recommended way to start Vigilon. If you would rather start it from code, call register() at the very top of your entry file, before any other require:
const { register } = require("@vigilon/node");
register({
environment: "staging",
excludedUrls: ["/internal/metrics"],
});
const express = require("express");
// ...the rest of your app
Every argument is optional: apiKey, serviceName, environment, serviceVersion, otelEndpoint, and excludedUrls. Anything you pass takes priority over the environment variables, and anything you leave out is found the usual way.
Starting from code only works in CommonJS apps. In an ES module app, every import is loaded before your code runs, so Vigilon starts too late to track your framework and database libraries. Use the --import flag or NODE_OPTIONS instead.
Use either the flag or register(), not both. If Vigilon is already running, a second register() logs a warning and does nothing.