;
};
This documentation outlines how to configure logging with the AppSignal for Node.js integration.
## Configure Logging
🔐 Do not send Personal Identifiable Information (PII) to AppSignal. Filter PII (e.g., names, emails) from logs and use an ID, hash, or pseudonymized identifier instead.
For **HIPAA-covered entities**, more information about signing a Business Associate Agreement (BAA) can be found in our [Business Add-Ons documentation](/support/business-add-ons).
You do not need to create a log source to send logs from the AppSignal for Node.js integration. An "application" log source will be created automatically.
### Stand-alone usage
To use the logger, you need to import AppSignal and set up the logger using the `.logger()` function.
The `.logger()` function accepts two arguments: `group` and optionally `severityThreshold`. If `severityThreshold` is not provided, it will default to `info`.
```javascript Node.js theme={null}
const { Appsignal } = require("@appsignal/nodejs");
const logger = Appsignal.logger("app");
// with a severity threshold:
const logger = Appsignal.logger("app", "info");
```
There are six severity levels available `trace`, `debug`, `info`, `log`, `warn`, and `error`, each of them with its own function with the same name. These functions accept two arguments `message` and `attributes`. Attributes is used for metadata and is optional.
Messages will only be logged if their severity level is above the severity threshold.
```javascript Node.js theme={null}
logger.info("Log message line");
logger.debug("User logged in", { user_id: 123 });
```
Note that if the message's severity is below the severity threshold set up when initializing the logger, it will not be sent to AppSignal.
You can query and filter on message contents and attribute values using our [query syntax](/logging/query-syntax).
#### Using multiple logging backends
It's currently not possible to send logs to multiple backends using Node.js' standard logger. For more complex setups, we recommend using a logging library like Winston or Pino.
### Usage with Winston
If you use Winston to log messages throughout your application, you can use our Winston transport to send those logs to AppSignal. After importing the transport from the AppSignal integration, add it to the list of transports in your Winston logger:
```javascript Node.js theme={null}
const winston = require("winston");
const { WinstonTransport } = require("@appsignal/nodejs");
const logger = winston.createLogger({
transports: [new WinstonTransport({ group: "app" })],
});
```
#### Child Logger
You can use a child logger to add additional tags to log messages. You define tags when creating the child logger constant or pass tags as metadata when writing a log message. Say we want greater context in our logs of the actions of a particular user within a specific session. In the below example, a child logger for the `background` group is used to add `sessionID` with the additional `drinkID`, and `paymentID` tags are provided as metadata when creating a log message, and if a group is given to the child, it'll override the one set up in the transport.
```javascript Node.js theme={null}
const logger = winston.createLogger({...});
const sessionLogger = logger.child({
group: "background",
sessionID: user.id,
});
sessionLogger.debug("User logged in");
sessionLogger.info("User ordered coffee", { drinkID: 30, paymentID: 20082 });
sessionLogger.debug("User logged out");
```
#### Using multiple logging backends
To send logs to both AppSignal's logger and `STDOUT`, add another transport:
```javascript JavaScript theme={null}
const winston = require("winston");
const { WinstonTransport } = require("@appsignal/nodejs");
const logger = winston.createLogger({
transports: [
new WinstonTransport({ group: "app" }),
new winston.transports.Console(),
],
});
```
### Usage with Pino
If Pino is your preferred logging library, you can use the AppSignal Pino transport to send logs to AppSignal.
The group argument will default to "app" if not provided.
```javascript Node.js theme={null}
import pino from "pino";
const logger = pino({
transport: {
targets: [
{ target: "@appsignal/nodejs/pino", options: { group: "my-group" } }
],
},
});
```
#### Using multiple logging backends
To send logs to both AppSignal's logger and `STDOUT`, add another target:
```javascript Node.js theme={null}
import pino from "pino";
const logger = pino({
transport: {
targets: [
{ target: "@appsignal/nodejs/pino", options: { group: "my-group" } },
{ target: 'pino/file', options: {destination: 1} }
],
},
});
```
## Formats
### Auto detected format
The AppSignal for Node.js package will automatically detect the log line's format as JSON, Logfmt or plaintext by default, and parse attributes from it.
You don't need to manually set the log format, unless it's not being detected properly.
Please also [notify us](mailto:support@appsignal.com?subject=Log%20format%20auto%20detection%20not%20working) if this isn't working automatically.
```javascript Node.js theme={null}
const { Appsignal } = require("@appsignal/nodejs");
// Plaintext format
const logger = Appsignal.logger("app", "info");
logger.info("This is about the blog");
// Logfmt format
const logger = Appsignal.logger("app", "info");
logger.info("category=blog This is about the blog");
// JSON format
const logger = Appsignal.logger("app", "info");
logger.info('{"category": "blog", "message": "This is about the blog"}');
```
### Logfmt
The AppSignal Logger can be explicitly configured to expect the line to be formatted as Logfmt and parse attributes from it.
Use this option when using an older AppSignal for Node.js package version, which does not support [automatic format detection](#auto-detected-format).
The log format can be specified when creating a logger.
When initializing the AppSignal logger pass the `"logfmt"` value as the third argument.
```javascript Node.js theme={null}
const { Appsignal } = require("@appsignal/nodejs");
const logger = Appsignal.logger("app", "info", "logfmt");
logger.info("category=blog this is about the blog");
```
In the example above, a filterable category attribute with the value "blog" will be logged.
### JSON
The AppSignal Logger can be explicitly configured to expect the line to be formatted as JSON and parse attributes from it.
Use this option when using an older AppSignal for Node.js package version, which does not support [automatic format detection](#auto-detected-format).
The log format can be specified when creating a logger.
When initializing the AppSignal logger pass the `"json"` value as the third argument.
```javascript Node.js theme={null}
const { Appsignal } = require("@appsignal/nodejs");
const logger = Appsignal.logger("app", "info", "json");
logger.info('{"category": "blog", "message": "this is about the blog"}');
```
In the example above, a filterable category attribute with the value "blog" will be logged.
## Filtering Logs
You can use [the `ignoreLogs` configuration option](/nodejs/3.x/configuration/options#option-ignorelogs) to ignore log lines based on their message. See [our Ignore Logs guide](/guides/filter-data/ignore-logs) to learn more.
## Need Help?
After configuring your Node.js application to send logs, logs should appear in AppSignal. If you are unsure about this step or AppSignal is not receiving any logs, you can always [reach out](mailto:support@appsignal.com) for assistance. We'll help get you back on track!