JavaScript

Collect logs from both Node.js backend and your frontend.

Example

It's very easy to start sending logs to Logtail:

const { Logtail } = require("@logtail/node");
const logtail = new Logtail("<source-token>");
logtail.info("logtail integration is ready");
logtail.warn("log structured data", {
item: {
url: "https://fictional-store.com/item-123",
price: 100.00
}
});

As a result, the following JSON rows will be ingested:

{
"dt": "2021-03-29T11:24:54.788Z",
"level": "info",
"message": "logtail integration is ready"
}
{
"dt": "2021-03-29T11:24:54.788Z",
"level": "warn",
"message": "log structured data",
"item": {
"url": "https://fictional-store.com/item-123",
"price": 100.00
}
}

Installation

Node.js
Frontend (NPM)
Frontend (UMD)
Node.js

Simply install the library from NPM:

npm install @logtail/node

Then you can require it or import in your codebase:

// start by loading the Logtail class
const { Logtail } = require("@logtail/node");
// ... or if you're using ES modules:
import { Logtail } from "@logtail/node";

If your project contains both Node.js and frontend code, you can use our universal package @logtail/js which combines the node and browser packages:

// in your backend code:
const { Node: Logtail } = require("@logtail/js");
// in your frontend code:
import { Browser as Logtail } from "@logtail/js";

Frontend (NPM)

You can simply install the library from NPM:

npm install @logtail/browser

... and import it into your JavaScript code as you're used to:

import { Logtail } from "@logtail/browser";
Frontend (UMD)

You can use the UMD build directly from a CDN:

<script src="https://unpkg.com/browse/@logtail/[email protected]/dist/umd/logtail.js"></script>

Integrations

We provide integrations with several existing frameworks and logging solutions.

Koa
Winston
Bunyan
Koa

Install the following @logtail/koa NPM package and then attach the Logtail instance as a middleware to your Koa instance:

const Koa = require("koa");
const { Logtail } = require("@logtail/koa");
// Create a new Koa instance
const koa = new Koa();
// Create a new Logtail client
const logtail = new Logtail("logtail-source-token");
// Attach Koa to enable HTTP request logging
logtail.attach(koa);

How the middleware works

Successful requests

A successful request is one that returns a non-4xx or 5xx status code, and doesn't throw any uncaught errors while handling the requests. These are logged to Logtail using LogLevel.Info

4xx status codes

These are not considered errors but warnings and log with the same message using LogLevel.Warn

5xx status codes

Responses that contain a 5xx status code are considered errors and are logged with LogLevel.Error

Additional logging

Since this Koa plugin extends the regular @logtail/node logger, you can use the .log|info|warn|error functions as normal to handle logging anywhere in your app.

Winston

Install the @logtail/winston NPM package and set up the Logtail transport according to the following example:

const winston = require("winston");
const { Logtail } = require("@logtail/node");
const { LogtailTransport } = require("@logtail/winston");
// Create a Logtail client
const logtail = new Logtail("logtail-source-token");
// Create a Winston logger - passing in the Logtail transport
const logger = winston.createLogger({
transports: [new LogtailTransport(logtail)],
});
// Log as normal in Winston - your logs will sync with Logtail.com!
logger.log({
level: "info", // <-- will use Logtail's `info` log level,
message: "Some message", // <-- will also be passed to Logtail
});
Bunyan

Install the @logtail/bunyan NPM package and set up the Logtail stream according to the following example:

const bunyan = requrie("bunyan");
const { Logtail } = require("@logtail/node");
const { LogtailStream } = require("@logtail/bunyan");
// Create a Logtail client
const logtail = new Logtail("logtail-source-token");
// Create a Bunyan logger - passing in the Logtail stream
const logger = bunyan.createLogger({
name: "Example logger",
level: "debug",
streams: [
{
stream: new LogtailStream(logtail),
},
],
});
// Log as normal in Bunyan - your logs will be sent to Logtail.com
logger.info("Hello from Bunyan");

Usage

Setting up the integration is very easy. All you need is a source-token that you'll get after you create a Source in your logtail.com account. With the source token at hand, you can create a Logtail instance and start logging:

const logtail = new Logtail("<your-source-token>");
logtail.info("simple log message");
logtail.warn("warning with additional information", {
resource: {
type: "store-item",
id: 123456,
inStock: false
}
});

The first argument is either a string message or an instance of Error. The second argument is an optional object, which can contain a tree structure with string, numeric, boolean, and Date values.

There are four levels of log messages: debug, info, warn, and error. You can either log by calling the respective functions on the Logtail object, or you can pass the level as an additional parameter to the generic log function:

import { LogLevel } from "@logtail/types";
// note: you don't need to install any additional packages
logtail.log("this is important", LogLevel.Error);

Middleware

You can intercept every logged item and modify it before it's pushed to Logtail. This could be useful for example for adding the current user's ID to the log:

async function enrichLogs(log) {
return {
...log,
userId: getCurrentUserId()
};
}
logtail.use(enrichLogs);

TypeScript support

If you're using Logtail in a TypeScript codebase, you can take advantage of our types. The custom middleware function from the previous example could look like this:

import { ILogtailLog } from "@logtail/types";
async function enrichLogs(log: ILogtailLog): Promise<ILogtailLog> {
return {
...log,
userId: getCurrentUserId()
};
}