18e7fded4SWill Gardner# Phosphor
2ef0b9a6fSWill Gardner
3c7a0cdd0SWill Gardner[![License](https://img.shields.io/github/license/couchbaselabs/phosphor.svg)](LICENSE.txt)
43475a777SWill Gardner
5ef0b9a6fSWill GardnerPhosphor is a high-performance event tracing framework for C++11 applications
6ef0b9a6fSWill Gardnerdesigned for use in Couchbase Server - specifically KV Engine and ForestDB.
7ef0b9a6fSWill Gardner
8ef0b9a6fSWill GardnerEvent tracing is implemented in an application by instrumenting it as
9ef0b9a6fSWill Gardnerdescribed in [phosphor.h](include/phosphor/phosphor.h). You can then enable
10ef0b9a6fSWill Gardnerand manage tracing using the management API described in
11ef0b9a6fSWill Gardner[trace_log.h](include/phosphor/trace_log.h).
12ef0b9a6fSWill Gardner
13ef0b9a6fSWill Gardner## Example
14ef0b9a6fSWill GardnerThe following is an example of hypothetical instrumentation in memcached:
15ef0b9a6fSWill Gardner
16ef0b9a6fSWill Gardner    void performSet(ENGINE_HANDLE* engine, const char* key, const char* value) {
1753874a42STrond Norbye        TRACE_EVENT_START("Memcached:Operation", "performSet", key);
18ef0b9a6fSWill Gardner        // Perform a set operation
1953874a42STrond Norbye        TRACE_EVENT_END0("Memcached:Operation", "performSet");
20ef0b9a6fSWill Gardner    }
21ef0b9a6fSWill Gardner
22ef0b9a6fSWill GardnerThe following is an example of enabling tracing with a fixed-style 5MB buffer:
23ef0b9a6fSWill Gardner
2453874a42STrond Norbye    phosphor::TraceConfig config(phosphor::BufferMode::fixed, 5 * 1024 * 1024);
2553874a42STrond Norbye    phosphor::TraceLog::getInstance().start(config);
26a03e5750SWill Gardner
27508abd66SWill GardnerOnce the trace buffer becomes full you can retrieve it and iterate over it:
28508abd66SWill Gardner
2953874a42STrond Norbye    auto trace_buffer = phosphor::TraceLog::getInstance().getBuffer();
30508abd66SWill Gardner    for(auto& event : *trace_buffer) {
31508abd66SWill Gardner        std::cout << event << '\n';
32508abd66SWill Gardner    }
33a03e5750SWill Gardner
34508abd66SWill Gardner## Build
35508abd66SWill Gardner
36a03e5750SWill GardnerPhosphor is written in C++11 and requires a mostly conforming compiler. Many
37508abd66SWill Gardnerearly C++11 implementations used slow or even inaccurate clock sources which can
38508abd66SWill Gardnercause issues with tracing.
39508abd66SWill Gardner
40508abd66SWill GardnerPhosphor can be built with CMake, a top level Makefile is provided for
41508abd66SWill Gardnerconvenience. A simple `make compile` and `make test` will compile and run the
42508abd66SWill Gardnertests.
43508abd66SWill Gardner
44508abd66SWill GardnerPhosphor can be built and tested with code coverage by running `make covered`.
45508abd66SWill Gardner
46ef0b9a6fSWill Gardner## Documentation
47ef0b9a6fSWill Gardner
48508abd66SWill GardnerDocumentation for Phosphor can be found on
49c0c7e644SDave Rigby[couchbase.github.io/phosphor](http://couchbase.github.io/phosphor/). The
50c0c7e644SDave Rigbydocumentation is generated by Doxygen and can be done using `make
51c0c7e644SDave Rigbydocs` with the top level Makefile.
52