Skip to content

Docs: Update docs for the new native sdk #1517

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Mar 2, 2020
Merged

Docs: Update docs for the new native sdk #1517

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8e3898d
update docs for the new native sdk
Swatinem Feb 28, 2020
ebdaf01
add a notice for on-premise users, clear up other docs
Swatinem Mar 2, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
178 changes: 70 additions & 108 deletions src/collections/_documentation/platforms/native/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,19 @@
title: Native
---

{% capture __alert_content -%}
Support for `sentry-native` is currently limited to the hosted version on
[`sentry.io`](https://sentry.io). The latest on-premise version of Sentry
(*10.0*) does not provide server-side support for events sent by
`sentry-native`. Full support for `sentry-native` will be made available to all
on-premise customers with the next release.
{%- endcapture -%}
{%- include components/alert.html
title="Sentry On-Premise"
content=__alert_content
level="warning"
%}

The Sentry Native SDK is intended for C and C++. However, since it builds as a
dynamic library and exposes C-bindings, it can be used by any language that
supports interoperability with C, such as the Foreign Function Interface (FFI).
Expand All @@ -21,57 +34,37 @@ without using the Native SDK, see the following resources:

## Integrating the SDK

The Native SDK currently supports **Windows, macOS and Linux**. There are three
distribution to choose from:

| Standalone | With Breakpad | With Crashpad |
| :----------------: | :-------------: | :-------------: |
| Custom Messages | Custom Messages | Custom Messages |
| Custom Errors | Custom Errors | Custom Errors |
| Breadcrumbs | Breadcrumbs | Breadcrumbs |
| _Stack Traces*_ | Stack Traces | Stack Traces |
| _Capture Crashes*_ | Capture Crashes | Capture Crashes |
| --- | Minidumps | Minidumps |
| --- | Attachments | Attachments |

\* _Adding stack traces and capturing application crashes requires you to add an
unwind library and hook into signal handlers of your process. The Standalone
distribution currently does not contain integrations that perform this
automatically._
The Native SDK currently supports **Windows, macOS, Linux and Android**.

### Building the SDK

To build the SDK, download the latest release of the SDK from the [Releases
page](https://github.com/getsentry/sentry-native/releases). For each supported
platform, there is a `gen_*` subfolder that contains build files:

**Windows**

: `gen_windows` contains a Microsoft Visual Studio 2017 solution. Open the
solution and add your projects or copy the projects to an existing solution.
Each project supports a debug and release configuration and includes all
sources required for building.

**Linux and macOS**

: `gen_linux` and `gen_macos` contain Makefiles that can be used to produce
dynamic libraries. Run `make help` to see an overview of the available
configurations and target. There are debug and release configurations, that
can be toggled when building:

```bash
make config=release sentry
```

There are multiple available targets to build:
page](https://github.com/getsentry/sentry-native/releases).
The SDK is managed as a [CMake] project, which additionally supports a number
of configuration options, such as the backend to use.

`CMake` can be used for example like this (on macOS):

```sh
# configure the cmake build into the `build` directory, with crashpad (on macOS)
$ cmake -B build -D SENTRY_BACKEND=crashpad
# build the project
$ cmake --build build --parallel
# install the resulting artifacts into a specific prefix
$ cmake --install build --prefix install
# which will result in the following (on macOS):
$ exa --tree install
install
├── bin
│ └── crashpad_handler
├── include
│ └── sentry.h
└── lib
├── libsentry.dylib
└── libsentry.dylib.dSYM
```

- `sentry`: Builds the Native SDK built as a dynamic library.
- `sentry_breakpad`: Builds the Native SDK with Google Breakpad as a dynamic
library.
- `sentry_crashpad`: Builds the Native SDK with Google Crashpad as a dynamic
library.
- `crashpad_*`: Builds crashpad utilities. To run the Crashpad distribution of
the SDK, you must build `crashpad_handler` and ship it with your application.
[cmake]: https://cmake.org/cmake/help/latest/

### Connecting the SDK to Sentry

Expand Down Expand Up @@ -365,11 +358,11 @@ transport depends on the target platform:

- **Linux**: Curl
- **macOS**: Curl
- **Windows**: WinHTTP

To specify a custom transport, use the `sentry_options_set_transport` function
and supply a transport that conforms to the `sentry_transport_function_t`
signature:
and supply a transport that implements the `sentry_transport_t` interface.
To simplify using a single function, one might use the
`sentry_new_function_transport` function:

```c
#include <sentry.h>
Expand All @@ -387,7 +380,8 @@ int main(void) {
void *transport_data = 0;

sentry_options_t *options = sentry_options_new();
sentry_options_set_transport(options, custom_transport, transport_data);
sentry_options_set_transport(options,
sentry_new_function_transport(custom_transport, transport_data));
sentry_init(options);

/* ... */
Expand All @@ -402,38 +396,14 @@ background thread or thread pool to avoid blocking execution.

*Integrations* extend the functionality of the SDK for some common frameworks
and libraries. Similar to plugins, they extend the functionality of the Sentry
SDK. The Native SDK comes in two additional distributions that include
integrations into the Breakpad and Crashpad libraries, respectively.

### Google Breakpad
SDK.

[Breakpad](https://chromium.googlesource.com/breakpad/breakpad/) is an
open-source multiplatform crash reporting system written in C++ by Google and
the predecessor of Crashpad. It supports macOS, Windows, and Linux, and features
an uploader to submit minidumps to a configured URL right when the process
crashes.

To use the Breakpad integration with the Native SDK, build and link the
`sentry_breakpad` dynamic library. Then, configure a path at which Breakpad can
store its database. This location temporarily hosts Minidumps before they are
uploaded to Sentry.

```c
sentry_options_t *options = sentry_options_new();
sentry_options_set_database_path(options, "sentry-db");
sentry_init(options);
```
The Native SDK can use different backends that are responsible to capture
crashes. The backend is configured at build-time, using the `SENTRY_BACKEND`
CMake option.

{% capture __alert_content -%}
Breakpad on macOS has been deprecated. If you are setting up a new project,
consider to use the [Crashpad distribution](#google-crashpad) instead. The
Sentry SDK is subject to limitations of Breakpad.
{%- endcapture -%}
{%- include components/alert.html
title="Warning"
content=__alert_content
level="warning"
%}
The `crashpad` backend is used by default on Windows and macOS, whereas Linux
and Android use the `inproc` in-process backend by default.

### Google Crashpad

Expand All @@ -442,51 +412,43 @@ is an open-source multiplatform crash reporting system written in C++ by Google.
It supports macOS, Windows, and Linux (limited), and features an uploader to
submit minidumps to a configured URL right when the process crashes.

To use the Crashpad integration with the Native SDK, build and link the
`sentry_crashpad` dynamic library. Additonally, build the standalone
`crashpad_handler` application. Then, configure a path at which Crashpad can
store its database. This location temporarily hosts Minidumps before they are
uploaded to Sentry.
To use the Crashpad backend with the Native SDK, configure the CMake build
with the `SENTRY_BACKEND=crashpad` option. This will automatically create a
`crashpad_handler` executable alongside the `sentry` library.

```sh
$ cmake -B build -D SENTRY_BACKEND=crashpad
```

The SDK will automatically look for a `crashpad_handler` executable in the same
directory as the running application. It will also use the `.sentry-native`
directory as its database by default, relative to the current working directory
of your application.
This location temporarily hosts Minidumps before they are uploaded to Sentry.

Both of these paths can be customized like this:

```c
sentry_options_t *options = sentry_options_new();
sentry_options_set_handler_path(options, "path/to/crashpad_handler");
sentry_options_set_database_path(options, "sentry-db");
sentry_options_set_database_path(options, "sentry-db-directory");
sentry_init(options);
```

The crashpad handler executable must be shipped alongside your application so
that it can be launched when initializing the SDK. The path is evaluated
relative to the current working directory at runtime.

{% capture __alert_content -%}
We do not recommend to run Crashpad on Linux as development of the Crashpad
library for Linux has not been completed. The Sentry SDK is subject to
limitations of Crashpad, which on Linux include:

- No support for HTTPs uploads. Crash reports can only be uploaded to Sentry
using insecure HTTP connections.
- Limited crash handler support. In some cases, the crash handler may be
unstable or not capture the process state correctly.

Consider to use the [Breakpad distribution](#google-breakpad) instead.
{%- endcapture -%}
{%- include components/alert.html
title="Warning"
content=__alert_content
level="warning"
%}

### Event Attachments (Preview)
## Event Attachments (Preview)

Besides the Minidump file, Sentry can optionally store additional files uploaded
in the same request, such as log files.

{% include platforms/event-attachments.md %}

Attachments require the _Crashpad_ distribution of the SDK. To add an
attachment, the path to the file has to be configured when initializing the SDK.
It will monitor the file and add it to any Minidump that is sent to Sentry:
To add an attachment, the path to the file has to be configured when
initializing the SDK. It will monitor the file and upload it along any event
or crash that is sent to Sentry:

```c
sentry_options_add_attachment(options, "log", "/var/server.log");
Expand Down