Purpose

This package provides services for logging. Optional Sentry, Axiom, and Loggly integrations are included.

This package also exports some CRUD utilities for managing log topics and subscriptions (used by the Slack integration).

Docs

Docs generated via typedoc live at Vercel here.

Usage

Usually you'll want to instantiate a single Loggler instance for your whole app to benefit from internal topic/subscription caching.

Note

See the parachute-secrets docs for more info about how we manage application secrets.

For example:

// ~/clients/loggler.ts
import { Loggler } from '@parachutehome/loggler';
import packageJson from '../../package.json';
import { isLocal } from '~/constants';

export const loggler = new Loggler({
    appName: packageJson.name,
    appVersion: packageJson.version,
    sentry: {
        enabled: !isLocal,
        defaultLogLevel: 'error',
        /**
         * Replace this with the relevant secret for your app.
         */
        dsnSecret: 'MY_APP_SENTRY_DSN',
    },
    slack: {
        enabled: true,
        /**
         * Replace this with the relevant secret for your app.
         */
        tokenSecret: 'MY_APP_SLACK_TOKEN',
    },
    axiom: {
        enabled: !isLocal,
        defaultLogLevel: 'info',
        /**
         * Replace this with the relevant secret for your app.
         */
        datasetNameSecret: 'MY_APP_AXIOM_DATASET',
        tokenSecret: 'AXIOM_INGEST_TOKEN',
    },
});

Then, elsewhere in your app you can instantiate namespaced loggers as needed. For example:

import { loggler } from '~/clients/loggler';

const logger = loggler.createLogger({
    /**
     * This is used to namespace your logs. Helpful for searching Axiom etc.
     */
    context: 'services/myService',
    /**
     * This is optional, but can be used to enable Slack subscriptions.
     */
    topic: 'orders:someEventHappened',
});

To utilize Slack subscriptions for given topics, you can use Umbrella UI to manage topics and subscriptions.

Now you can use the instantiated logger to do normal log stuff. Log functions are async, but you can choose to await them or not depending on your use cases. For example:

logger.error(error).catch(() => {
    // Log failed for some reason
})
await logger.warn('Something bad happened.');

You can also set topic/subscription options on a granular basis with each function call, if it makes sense. For example:

await logger.debug(
    'This is a special message that has a topic set on the fly',
    { topic: 'customers:someEvent' },
);

You can also decide which messages will ping subscribed Slack users, if there are any defined in Umbrella. For example:

await logger.info(
    `New application submitted from ${firstName} ${lastName}`,
    {
        topic: 'hospitality:applicationSubmitted',
        pingSubscribers: true,
    },
);

You can see the above example in action in the #trade-applications Slack channel.