gruffins/birch-rn

Remote logger used with the Birch logging platform

Birch

Simple, lightweight remote logging for React Native.

Sign up for your free account at Birch

BIrch allows you to log to a variety of drains regardless of whether they have a native implementation or not. On top of that, Birch provides the ability to remotely adjust log configurations on any of your apps in production.

Birch can drain to

• New Relic
• Datadog
• Logtail
• Loggly
• Elasticsearch
• Papertrail
• Logz
• CloudWatch
• S3
• Wasabi
• Google Cloud Logging
• A custom webhook

Installation

npm i react-native-birch

Setup

import Birch from 'react-native-birch';
import { useEffect, useState } from 'react';

export default function App() {
  const [userId, setUserId] = useState('');

  useEffect(() => {
    Birch.init({
      apiKey: '',
      publicKey: '',
    });
    
    Birch.setConsole(true);
  }, []);

  useEffect(() => {
    Birch.setIdentifier(userId);
  }, [userId]);
}

Logging

Use the logger as you would with console logs.

Birch.t('trace level message');
Birch.d('debug level message');
Birch.i('info level message');
Birch.w('warn level message');
Birch.e('error level message');

Configuration

Device level configuration is left to the server so you can remotely control it. There are a few things you can control on the client side.

Console

During local development, it is useful to see the logs in the console. These console logs are not useful in production since you cannot read them remotely. The default is false. Setting this will affect console logs on iOS and Logcat on Android.

Birch.setConsole(true);

const useConsole = await Birch.getConsole();

Remote

During local development, it's unlikely that you'll need remote logging. You cna optionally turn it off to minimize your usage on Birch. The default is true.

Birch.setRemote(true);

const remote = await Birch.getRemote()

Level

During local development, you may want to quickly override the server configuration. The default is null which allows teh server to set the remote level. Setting a value will ALWAYS override the server and prevent you from being able to remotely adjust the level.

Birch.setLevel(Level.Trace)

const level = await Birch.getLevel();

Synchronous

During local development, you may want logs to print immediately when you're stepping through with a debugger. To do this, you'll need to use synchronous logging. The default value is false. Synchronous logging is slower since it has to perform the logging inline.

Birch.setSynchronous(true);

const sync = await Birch.getSynchronous();

Debug

When integrating the library, you may be curioius to see the logger at work. By setting debug to true, Birch will log its operations. The default value is false. You should NOT set this to true in a production build.

You will only be able to see these logs in the native iOS console logs or Logcat.

Birch.setDebug(true);

const debug = await Birch.getDebug();

Encryption

We HIGHLY recommend using encryption to encrypt your logs at rest. If you leave out the public encryption key, Birch will save logs on the device in clear text.

An invalid public key will throw an exception.

Identification

You should set an identifier so you can identify the source in the dashboard. If you do not set one, you will only be able to find devices by the assigned uuid via Birch.uuid().

You can also set custom properties on the source that will propagate to all drains.

Birch.setIdentifier('user_id');
Birch.setCustomProperties({
  country: user.country,
});

Opt Out

To comply with different sets of regulations such as GDPR or CCPA, you may be required to allow users to opt out of log collection.

Birch.setOptOut(true);

const optOut = await Birch.getOptOut();

Log Scrubbing

Birch comes preconfigured with an email and password scrubber to ensure sensitive data is NOT logged. Emails and passwords are replaced with [FILTERED] at the logger level so the data never reaches Birch servers.

If you wish to configure additional scrubbers, implement the scrubbing function and initialize the logger with all the scrubbers you want to use.

import { emailScrubber, passwordScrubber } from 'react-native-birch';

function customScrubber(input: string): string {
  return input.replaceAll(REGEX, '[FILTERED]');
}

export default function App() {
  useEffect(() => {
    Birch.init({
      apiKey: '',
      publicKey: '',
      options: {
        scrubbers: [customScrubber, emailScrubber, passwordScrubber],
      }
    })
  }, [])
}