npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@timberio/koa

v0.35.0

Published

Timber.io - Koa logger

Downloads

16

Readme

🌲 Timber - Koa logging

Beta: Ready for testing Speed: Blazing ISC License

New to Timber? Here's a low-down on logging in Javascript.

@timberio/koa

This NPM library is for logging Koa HTTP web server requests.

It extends the Timber Node JS library with Koa middleware.

Installation

Install the package directly from NPM:

npm i @timberio/koa

Importing

In ES6/Typescript, import the Timber class:

import { Timber } from "@timberio/koa";

For CommonJS, require the package:

const { Timber } = require("@timberio/koa");

Creating a client

Simply pass your Timber.io API key as a parameter to a new Timber instance:

const timber = new Timber("timber-organization-key", "timber-source-key");

Timber accepts two optional, additional parameters:

  1. Core logging options, allowing you to tweak the interval logs will be sent to Timber.io, how many concurrent network connections the logger should use, and more. See type ITimberOptions for details.

  2. Koa logging options, specified below.

These can be passed when creating a new Timber instance as follows:

const timberOptions = {
  /**
   * For example -- setting the maximum number of sync requests to
   * make concurrently (useful to limit network I/O)
   */
  syncMax: 10
};

const koaOptions = {
  // Override default Koa context data to include in each log
  contextPaths: ["statusCode", "request.headers", "request.method"]
};

const timber = new Timber(
  "timber-organization-key",
  "timber-source-key",
  timberOptions,
  koaOptions
);

Attaching to Koa

To activate the plugin and enable logging, simply attach a Koa instance:

import Koa from "koa";
import { Timber } from "@timberio/koa";

// Create a new Koa instance
const koa = new Koa();

// Create a new Timber client
const timber = new Timber("timber-organization-key", "timber-source-key");

// Attach Koa to enable HTTP request logging
timber.attach(koa);

Koa options

Koa options passed to a new Timber are of type IKoaOptions:

interface IKoaOptions {
  /**
   * Properties to pluck from the Koa `Context` object
   */
  contextPaths: string[];
}

Here are the default properties, which can be overridden:

contextPaths

A string[] of paths to pluck from the Koa ctx object, which contains details about the request and response of a given Koa HTTP call.

Nested object properties are separated using a period (.)

[
  "statusCode",
  "request.headers",
  "request.method",
  "request.length",
  "request.url",
  "request.query"
];

How logging works

All HTTP requests handled by Koa will be logged automatically, and synced with the Timber.io service, to the source defined by your Timber API key.

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 Timber using LogLevel.Info with the log message:

Koa HTTP request: ${ctx.status}

4xx status codes

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

A typical example of a 4xx class of response would be 404 Not Found or 401 Unauthorized.

5xx status codes

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

An example of a 5xx status code is 500 Internal Server Error - typically indicating that something unexpected has happened.

Uncaught errors

If an error is thrown in Koa middleware and remains uncaught, the Timber middleware handling will catch, log it with LogLevel.Error and re-throw, to handle in your own code.

The log message will be:

`Koa HTTP request error: ${(typeof e === "object" && e.message) || e}`

If the error thrown is a regular Node.js error object (i.e. has a .message property), it will be interpolated with the log message.

Otherwise, an attempt will be made to stringify the message.

If your app throws non-errors, it's recommended that you catch the thrown entity in your code and throw a regular Node.js instead, to provide a useful string message to your log.

Additional logging

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

See the Timber Node.js logger documentation for details.

LICENSE

ISC