Introduction

BCD is a simple library for invoking out-of-process tools in response to program errors. By default, BCD is configured to use the Backtrace I/O tracers and database clients to allow for process snapshots to be directly submitted to the database.

Supported Platforms

BCD currently only supports Linux, but FreeBSD and IllumOS support is planned. GCC, clang and ICC are supported. Though BCD must be built with a C compiler that supports GNU99, the BCD interface is C++ compatible.

Dependencies

For glibc versions before 2.17, librt is required.

Build

To use BCD as a stand-alone library, use:

./configure
make
make install

It is possible to use BCD in amalgamated mode so that you only need to drop in a header and source file in your source tree. In order to do this, you would do the following:

./configure
make amalgamated

The source file is in src/bcd-amalgamated.c and the header file is include/bcd.h. Just drop those in your source-tree.

Usage

For a simple example, please look at regressions/broad.c. For more detailed documentation, please refer to include/bcd.h.

In order to initialize the library, you must call bcd_init. This will initialize the library for use. If you would like to emit non-fatal errors, then you must also use bcd_attach to initialize a bcd_t object. Every thread must use a unique bcd_t object. These bcd_t objects may be destroyed with bcd_detach.

You may use bcd_emit to request a snapshot of a non-fatal error. The error will be grouped according to the error message passed to bcd_emit. For fatal errors, you may call bcd_fatal. BCD will exit and deinitialize after a call to bcd_fatal, so it is expected that your program will exit at this point.

Credentials, permission, OOM killer interaction and more may be configured with the bcd_config data structure, please see bcd.h for details.

Example

#include <bcd.h>
#include <stdio.h>
#include <stdlib.h>

int
main(void)
{
	struct bcd_config config;
	bcd_error_t error;
	bcd_t bcd;

	/* Initialize BCD configuration. See bcd.h for options */
	if (bcd_config_init(&config, &error) == -1)
		goto fatal;

	/* Initialize the library. */
	if (bcd_init(&config, &error) == -1)
		goto fatal;

	/* Initialize a handle to BCD. */
	if (bcd_attach(&bcd, &error) == -1)
		goto fatal;

	if (bcd_kv(&bcd, "application", "my_application", &error) == -1)
		goto fatal;

	if (bcd_kv(&bcd, "datacenter", "my data center", &error) == -1)
		goto fatal;

	/*
	 * Generate a snapshot of the calling thread and upload it to
	 * the Backtrace database. Key-value attributes will be included.
	 */
	bcd_emit(&bcd, "This is a non-fatal error");

	/*
	 * We generate a fatal error and exit immediately.
	 */
	bcd_fatal("This is a fatal error. No recovery");
	return 0;
fatal:
	fprintf(stderr, "error: %s\n",
	    bcd_error_message(&error));
	exit(EXIT_FAILURE);
}

Limitations

For ease of use, bcd_emit and bcd_fatal do not provide return values. Error callbacks are used which are executed in the context of the BCD slave. A developer may wish to register their own callbacks if they wish to terminate their process due to error logging failures. BCD will never terminate the calling process itself.

BCD relies on a UNIX socket (by default, /tmp/bcd.*) for thread communications and relies on pipes for handling fatal errors and initial library configuration. If either of these facilities are erroneously closed, a fatal error will be generated by BCD, and BCD will exit. If this is a concern, then it is recommended to install your own error handler to kill the process that is being monitored.

BCD currently allocates memory in a separate process on errors, which may not be suitable for systems that lack overcommit.

Design

BCD will initialize a pipe and fork a process during bcd_init. This child will initialize a UNIX socket for per-thread communications. The pipe is used early in initialization to communicate configuration errors and is used for fatal error handling. The BCD child process will fork and exec in response to trace requests.

All communication between the host application and BCD occurs in a synchronous fashion, for reasons of correctness. There is a global ordering to all BCD operations.

abelmathew/bcd