nlohmann/crow

Crow - a C++ client for Sentry

Sentry is such a useful tool, but there is currently no official support for C++. Crow is an official Sentry client for C++ that tries to fill this gap to allow for Sentry notifications in long-running C++ applications where you do not want to constantly look at log files.

API

Setup

• nlohmann::crow::crow(dsn, context={}, sample_rate=1.0, install_handlers=true) to create a client
• nlohmann::crow::install_handler() to later install termination handler

Reporting

• nlohmann::crow::capture_message(message, attributes={}, async=true) to send a message
• nlohmann::crow::capture_exception(exception, context={}, async=true, handled=true) to send an exception
• nlohmann::crow::add_breadcrumb(message, attributes={}) to add a breadcrumb
• nlohmann::crow::get_last_event_id() to get the id of the last event

Context management

• nlohmann::crow::get_context() to return current context
• nlohmann::crow::add_user_context(const json& data) to add data to the user context
• nlohmann::crow::add_tags_context(const json& data) to add data to the tags context
• nlohmann::crow::add_request_context(const json& data) to add data to the request context
• nlohmann::crow::add_extra_context(const json& data) to add data to the extra context
• nlohmann::crow::merge_context(const json& context) to merge context information
• nlohmann::crow::clear_context() to reset context

See the documentation for a complete overview of the public API.

Requirements for Sentry SDKs

The following items from the SDK implementation guidelines are realized at the moment:

• The following items are expected of production-ready SDKs:
  • DSN configuration
  • Graceful failures (e.g. Sentry server is unreachable)
  • Setting attributes (e.g. tags and extra data)
  • Support for Linux, Windows and OS X (where applicable)
• Feature based support is required for the following:
  • If cookie data is available, it’s not sent by default
  • If POST data is available, it’s not sent by default
• Additionally, the following features are highly encouraged:
  • Automated error capturing (e.g. uncaught exception handlers)
  • Logging framework integration
  • Non-blocking event submission
  • Basic data sanitization (e.g. filtering out values that look like passwords)
  • Context data helpers (e.g. setting the current user, recording breadcrumbs)
  • Event sampling
  • Honor Sentry’s HTTP 429 Retry-After header
  • Pre and Post event send hooks
  • Local variable values in stacktrace (on platforms where this is possible)

Change Log

Version 0.0.6

• :arrow_down: made Crow work with CMake 3.8
• :arrow_up: upgraded shipped JSON for Modern C++ to 3.4.0

Version 0.0.5

• :sparkles: added event sampling
• :white_check_mark: added testing server to mock Sentry
• :memo: added example code
• :hammer: overworked threading

Version 0.0.4

• :sparkles: added Log4cplus integration

Version 0.0.3

• :sparkles: added functions to manage contexts
• :sparkles: made installation of termination handler more transparent
• :sparkles: made client thread-safe
• :sparkles: added gzip compression for requests
• :checkered_flag: overworked Windows version detection
• :construction_worker: added more compilers to CI
• :white_check_mark: added code coverage check

Version 0.0.2

• :construction_worker: integrated Travis and AppVeyor CI (#1)
• :memo: added Doxygen documentation as GitHub page (#4)
• :sparkles: added function to retrieve last event id (#8)
• :sparkles: collecting information on user, machine, operating system, and compiler
• :wheelchair: client now compiles with macOS, Linux, Windows (MinGW and MSVC)
• :heavy_minus_sign: removed Sole dependency for UUID generation
• :heavy_minus_sign: removed Date dependency for ISO8601 date string generation
• :white_check_mark: adding unit tests and live test client

Version 0.0.1

• :tada: initial release

Prerequisites

You need libcurl, zlib, and a C++11 compiler to use the library. Curl should be detected by CMake. If this does not work, you can download libcurl and zlib and pass the path to the source release folder to CMake via -DCROW_EXTERNAL_CURL_PROJECT=curl-7.61.0 and -DCROW_EXTERNAL_ZLIB_PROJECT=zlib-1.2.11. This libcurl and zlib is then built and linked.

License

The class is licensed under the MIT License:

Copyright © 2018 Niels Lohmann

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Used third-party tools

The library itself consists of a single header file licensed under the MIT license. However, it is built, tested, documented, and whatnot using a lot of third-party tools and services. Thanks a lot!

• Artistic Style for automatic source code identation
• Cmake for build automation
• Doxygen to generate documentation
• JSON for Modern C++ to use JSON datatypes inside C++
• libcurl for HTTP communication with the Sentry servers