Skip to content

Commit 352383d

Browse files
JoshuaMoelansAbhiPrasad
JoshuaMoelans
and
AbhiPrasad
authored
feat(native): add structured logs documentation (#15021)
Vercel previews Logs page https://sentry-docs-oflen3xm3.sentry.dev/platforms/native/logs/ Logs options https://sentry-docs-oflen3xm3.sentry.dev/platforms/native/configuration/options/#logs-options <!-- Use this checklist to make sure your PR is ready for merge. You may delete any sections you don't need. --> ## DESCRIBE YOUR PR We've finished logs for Native, so we should let people know how to use it getsentry/sentry-native#1271 ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. - [ ] Urgent deadline (GA date, etc.): <!-- ENTER DATE HERE --> - [ ] Other deadline: <!-- ENTER DATE HERE --> - [ ] None: Not urgent, can wait up to 1 week+ ## SLA - Teamwork makes the dream work, so please add a reviewer to your PRs. - Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it. Thanks in advance for your help! ## PRE-MERGE CHECKLIST *Make sure you've checked the following before merging your changes:* - [ ] Checked Vercel preview for correctness, including links - [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs) --------- Co-authored-by: Abhijeet Prasad <[email protected]>
1 parent 412d9eb commit 352383d

File tree

10 files changed

+116
-7
lines changed

10 files changed

+116
-7
lines changed

‎docs/platforms/native/common/configuration/options.mdx‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,3 +103,17 @@ A number between `0.0` and `1.0`, controlling the percentage chance a given tran
103103
A function responsible for determining the percentage chance a given transaction will be sent to Sentry. It will automatically be passed information about the transaction and the context in which it's being created, and must return a number between `0` (0% chance of being sent) and `1` (100% chance of being sent). Can also be used for filtering transactions, by returning 0 for those that are unwanted. Either this or <PlatformIdentifier name="traces-sample-rate" /> must be defined to enable tracing. An example can be found in the [Sampling](/platforms/native/configuration/sampling/#setting-a-sampling-function) section.
104104

105105
</ConfigKey>
106+
107+
## Logs options
108+
109+
<ConfigKey name="enable-logs">
110+
111+
This option enables the logging integration, which allows the SDK to capture logs and send them to Sentry. This is disabled by default.
112+
113+
</ConfigKey>
114+
115+
<ConfigKey name="before-send-log">
116+
117+
This function is called with an SDK-specific log object, and can return a modified log object, or `sentry_value_new_null()` to drop the log.
118+
119+
</ConfigKey>

‎docs/platforms/native/logs/index.mdx‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: Set Up Logs
3+
sidebar_title: Logs
4+
description: "Structured logs allow you to send, view and query logs sent from your applications within Sentry."
5+
sidebar_order: 5755
6+
---
7+
8+
With Sentry Structured Logs, you can send text-based log information from your applications to Sentry. Once in Sentry, these logs can be viewed alongside relevant errors, searched by text-string, or searched using their individual attributes.
9+
10+
## Requirements
11+
12+
<PlatformContent includePath="logs/requirements" />
13+
14+
## Setup
15+
16+
<PlatformContent includePath="logs/setup" />
17+
18+
## Usage
19+
20+
<PlatformContent includePath="logs/usage" />
21+
22+
## Options
23+
24+
<PlatformContent includePath="logs/options" />
25+
26+
## Default Attributes
27+
28+
<PlatformContent includePath="logs/default-attributes" />

‎docs/product/explore/logs/getting-started/index.mdx‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -282,6 +282,14 @@ To set up Sentry Logs, use the links below for supported SDKs. After it's been s
282282
url="/platforms/dotnet/guides/extensions-logging/logs/"
283283
/>
284284

285+
### Native
286+
287+
- <LinkWithPlatformIcon
288+
platform="native"
289+
label="Native"
290+
url="/platforms/native/logs"
291+
/>
292+
285293
## Upcoming SDKs
286294

287295
We're actively working on adding Log functionality to additional SDKs. Check out these GitHub issues for the latest updates:
@@ -301,10 +309,5 @@ We're actively working on adding Log functionality to additional SDKs. Check out
301309
label="Unreal"
302310
url="https://github.com/getsentry/sentry-unreal/issues/883"
303311
/>
304-
- <LinkWithPlatformIcon
305-
platform="native"
306-
label="Native"
307-
url="https://github.com/getsentry/sentry-native/issues/1210"
308-
/>
309312

310313
If you don't see your platform listed above, please reach out to us on [GitHub](https://github.com/getsentry/sentry/discussions/86804) or [Discord](https://discord.gg/sentry), we'll get it prioritized!

‎includes/logs/default-attributes/core.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,5 @@
33
- `environment`: The environment set in the SDK if defined. This is sent from the SDK as `sentry.environment`.
44
- `release`: The release set in the SDK if defined. This is sent from the SDK as `sentry.release`.
55
- `trace.parent_span_id`: The span ID of the span that was active when the log was collected (only set if there was an active span). This is sent from the SDK as `sentry.trace.parent_span_id`.
6-
- `sdk.name`: The name of the SDK that sent the log. This is sent from the SDK as `sentry.sdk.name`. This is sent from the SDK as `sentry.sdk.name`.
7-
- `sdk.version`: The version of the SDK that sent the log. This is sent from the SDK as `sentry.sdk.version`. This is sent from the SDK as `sentry.sdk.version`.
6+
- `sdk.name`: The name of the SDK that sent the log. This is sent from the SDK as `sentry.sdk.name`.
7+
- `sdk.version`: The version of the SDK that sent the log. This is sent from the SDK as `sentry.sdk.version`.

‎includes/logs/default-attributes/message-template-examples/native.mdx‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
For example, with the following log:
2+
3+
```c
4+
sentry_log_error("A %s log message", "formatted");
5+
```
6+
7+
Sentry will add the following attributes:
8+
9+
- `message.template`: "A %s log message"
10+
- `message.parameter.0`: "formatted"

‎platform-includes/logs/default-attributes/native.mdx‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
The Native SDK automatically sets several default attributes on all log entries to provide context and improve debugging:
2+
3+
<Include name="logs/default-attributes/core" />
4+
5+
<Include name="logs/default-attributes/message-template" />
6+
7+
<Include name="logs/default-attributes/message-template-examples/native" />
8+
9+
<Include name="logs/default-attributes/user-mobile" />

‎platform-includes/logs/options/native.mdx‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
#### before_send_log
2+
3+
To filter logs, or update them before they are sent to Sentry, you can use the `before_send_log` option.
4+
5+
```c
6+
static sentry_value_t
7+
before_send_log_callback(sentry_value_t log, void *user_data)
8+
{
9+
(void)user_data;
10+
sentry_value_t attribute = sentry_value_new_object();
11+
sentry_value_set_by_key(
12+
attribute, "value", sentry_value_new_string("little"));
13+
sentry_value_set_by_key(
14+
attribute, "type", sentry_value_new_string("string"));
15+
sentry_value_set_by_key(sentry_value_get_by_key(log, "attributes"),
16+
"coffeepot.size", attribute);
17+
return log;
18+
}
19+
20+
sentry_options_set_before_send_log(options, before_send_log_callback, NULL);
21+
```
22+
23+
24+
The `before_send_log` function receives a log object and optional `user_data`, and should return the log object if you want it to be sent to Sentry, or it should free the log using `sentry_value_decref(log)` and return a `sentry_value_new_null()` if you want to discard it.

‎platform-includes/logs/requirements/native.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Logs for Native are supported in Sentry Native SDK version `0.12.0` and above.

‎platform-includes/logs/setup/native.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
To enable logging, you need to initialize the SDK with the `enable_logs` option set to `true`.
2+
3+
```c
4+
sentry_options_t *options = sentry_options_new();
5+
sentry_options_set_enable_logs(options, true);
6+
// set other options
7+
sentry_init(options);
8+
```

‎platform-includes/logs/usage/native.mdx‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
Once the feature is enabled on the SDK and the SDK is initialized, you can send logs using the `sentry_log_X()` APIs.
2+
3+
The API exposes six methods that you can use to log messages at different log levels: `trace`, `debug`, `info`, `warn`, `error`, and `fatal`.
4+
5+
These properties will be sent to Sentry, and can be searched from within the Logs UI, and even added to the Logs views as a dedicated column.
6+
7+
```c
8+
import io.sentry.Sentry;
9+
10+
sentry_log_info("A simple log message");
11+
sentry_log_error("A %s log message", "formatted");
12+
```

0 commit comments

Comments
 (0)