CLI Quickstart¶

Pre-requisites¶

In order to be able to use the CLI, you need to have a bitdrift account.

Contact us at info@bitdrift.io to inquire about getting started.

Installation¶

The CLI is currently only supported on macOS and can be installed via Homebrew:

Bash

brew tap bitdriftlabs/bd
brew install bd

Usage¶

Authentication¶

The CLI relies on authenticating the user with the bitdrift SaaS to enforce access control. To authenticate, invoke

Bash

bd auth

This will open up a browser-based login flow where the user may log in via their preferred mechanism.

Log Tailing¶

To tail logs from devices connected to the bitdrift SaaS, use the bd tail command. This accepts a query expression that is used to specify both the devices to target as well as specifying what logs are of interest.

Log Tailing Query Expression¶

The query expression makes use of a series of operators which may accept a variable number of operator arguments. For example, the expression

Bash

bd tail apple field foo bar normal level debug

Would be parsed as (apple) (field foo bar) (level debug) and contain three operators:

apple - target all Apple (iOS) devices
field with the arguments foo and bar - only tail logs with field foo equal to bar
level with the argument debug - only tail logs at debug level

A complete list of operators can be found below:

apple - target all Apple (iOS) devices
android - target all Android devices
appversion <version> - target all devices with the specific app version
deviceid <id> - target the device with the specific bd device id device code
devicecode <code> / code <code> - target the device with the specific generated device code
appid <app id> - target all devices with the specific app id
level <level> / loglevel <type> - tail logs with the specificed log level
field <key> <value> / f <key> <value> - tail logs with field <key> = <value>

Log Formatting¶

When using the default output, logs are rendered with the log metadata and the log message. To modify the message rendered for each log, a VRL program can be provided which can be used to modify the displayed text as well as drop unnnecessary logs.

Within the configuration file located at ~/.bd/config.yaml or specified via the --config flag, specify the VRL program under the vrl_program key. For example:

YAML

vrl_program: |
  if .msg == "don't need this" {
    abort
  }

  if .field.foo == "foo_value" {
    msg = .msg
    bar_value = .field.bar

    . = "{{ msg }} {{ bar_value }}"
  }

Will drop all logs with the log message don't need this and will rewrite the displayed message for all logs with a field foo=foo_value to instead read <message> <value of field bar>.

The schema to keep in mind for the VRL programs:

.msg holds the log message
.field.<key> holds the value of field key or nil if not present
. used to specify how this log line should be rendered

Log Types¶

Each log is annotated with a log type that helps explain what kind of a log it is. Within the default bd tail output, this is rendered as the second column.

The possible values for the log type is

netw: Network logs emitted by various library integrations within the Capture SDK or via logNetworkRequest / logNetworkResponse.
resr: Resource logs emitted by the periodic resource monitors within the Capture SDK.
repl: Session replay logs emitted by the Capture SDK.
cstm: Custom logs fed into the Capture SDK via Logger.log methods.
othr: Other unclassified logs.