Skip to content

Commit 8cbdf54

Browse files
AbhiPrasadAbhiPrasad
authored
Document default sdk logging attributes (#14353)
<!-- Use this checklist to make sure your PR is ready for merge. You may delete any sections you don't need. --> ## DESCRIBE YOUR PR This PR updates the logging documentation for various SDKs to include a new "Default Attributes" section. The goal is to clearly inform users about the attributes automatically set by each SDK on log entries, providing better context for debugging. This is achieved by implementing a modular include structure, ensuring consistency and reusability of attribute definitions (core, user, server, browser, mobile) across different SDKs, along with SDK-specific message template details. resolves https://linear.app/getsentry/issue/LOGS-172/document-default-attributes-attached-to-a-log resolves https://linear.app/getsentry/issue/LOGS-276/update-sdk-docs-to-mention-body-is-required-in-usage-section ## 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 --> - [X] 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) ## LEGAL BOILERPLATE <!-- Sentry employees and contractors can delete or ignore this section. --> Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redist
1 parent 1558af3 commit 8cbdf54

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

60 files changed

+628
-166
lines changed

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,7 @@ With Sentry Structured Logs, you can send text-based log information from your a
2626
## Options
2727

2828
<PlatformContent includePath="logs/options" />
29+
30+
## Default Attributes
31+
32+
<PlatformContent includePath="logs/default-attributes" />

‎docs/platforms/apple/common/logs/index.mdx‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description: "Structured logs allow you to send, view and query logs sent from y
55
sidebar_order: 5755
66
---
77

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.
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.
99

1010
## Requirements
1111

@@ -22,3 +22,7 @@ With Sentry Structured Logs, you can send text based log information from your a
2222
## Options
2323

2424
<PlatformContent includePath="logs/options" />
25+
26+
## Default Attributes
27+
28+
<PlatformContent includePath="logs/default-attributes" />

‎docs/platforms/dart/common/logs/index.mdx‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@ description: "Structured logs allow you to send, view and query logs sent from y
55
sidebar_order: 5755
66
---
77

8-
98
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.
109

1110
## Requirements
@@ -27,3 +26,7 @@ With Sentry Structured Logs, you can send text-based log information from your a
2726
## Options
2827

2928
<PlatformContent includePath="logs/options" />
29+
30+
## Default Attributes
31+
32+
<PlatformContent includePath="logs/default-attributes" />

‎docs/platforms/dart/guides/flutter/logs/index.mdx‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@ description: "Structured logs allow you to send, view and query logs sent from y
55
sidebar_order: 5755
66
---
77

8-
98
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.
109

1110
## Requirements
@@ -23,3 +22,7 @@ With Sentry Structured Logs, you can send text-based log information from your a
2322
## Options
2423

2524
<PlatformContent includePath="logs/options" />
25+
26+
## Default Attributes
27+
28+
<PlatformContent includePath="logs/default-attributes" />

‎docs/platforms/dotnet/common/logs/index.mdx‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,6 @@ notSupported:
1111
- dotnet.xamarin
1212
---
1313

14-
1514
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.
1615

1716
## Requirements
@@ -33,3 +32,7 @@ With Sentry Structured Logs, you can send text-based log information from your a
3332
## Options
3433

3534
<PlatformContent includePath="logs/options" />
35+
36+
## Default Attributes
37+
38+
<PlatformContent includePath="logs/default-attributes" />

‎docs/platforms/go/common/logs/index.mdx‎

Lines changed: 12 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -5,129 +5,34 @@ description: "Structured logs allow you to send, view, and query logs sent from
55
sidebar_order: 5600
66
---
77

8-
98
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.
109

1110
## Requirements
1211

13-
Logs in Go are supported in Sentry Go SDK version `0.33.0` and above. To use integrations with other logging libraries, check their specific documentation pages for detailed requirements.
14-
15-
## Configure
16-
17-
### Initialize the Sentry SDK
18-
19-
To enable logging, you need to initialize the SDK with the `EnableLogs` option set to true.
20-
21-
<PlatformContent includePath="getting-started-include-logs-config" />
22-
23-
### Options
12+
<PlatformContent includePath="logs/requirements" />
2413

25-
#### BeforeSendLog
14+
## Setup
2615

27-
To filter logs, or update them before they are sent to Sentry, you can use the `BeforeSendLog` client option.
28-
29-
```go
30-
sentry.Init(sentry.ClientOptions{
31-
Dsn: "___PUBLIC_DSN___",
32-
EnableLogs: true,
33-
BeforeSendLog: func(log *sentry.Log) *sentry.Log {
34-
// filter out all trace logs
35-
if log.Level == sentry.LogLevelTrace {
36-
return nil
37-
}
38-
39-
// filter all logs below warning
40-
if log.Severity <= sentry.LogSeverityInfo {
41-
return nil
42-
}
43-
return log
44-
},
45-
})
46-
```
16+
<PlatformContent includePath="logs/setup" />
4717

4818
## Usage
4919

50-
Once the feature is enabled on the SDK and the SDK is initialized, you can send logs by using the `sentry.Logger` API or our different integrations.
51-
52-
The `sentry.Logger` API exposes methods that support six different log levels:
53-
- `trace`
54-
- `debug`
55-
- `info`
56-
- `warn`
57-
- `error`
58-
- `fatal`
59-
60-
The methods support both `fmt.Print` and `fmt.Printf` like syntax. If you pass in format specifiers like `%v`, these will be
61-
sent to Sentry, and can be searched from within the Logs UI, and even added to the Logs views as a dedicated column.
62-
63-
```go
64-
func main() {
65-
if err := sentry.Init(sentry.ClientOptions{
66-
Dsn: "___PUBLIC_DSN___",
67-
EnableLogs: true,
68-
}); err != nil {
69-
log.Fatalf("Sentry initialization failed: %v", err)
70-
}
71-
// Flush buffered events before the program terminates.
72-
// Set the timeout to the maximum duration the program can afford to wait.
73-
defer sentry.Flush(2 * time.Second)
74-
75-
// The SentryLogger requires context, to link logs with the appropriate traces. You can either create a new logger
76-
// by providing the context, or use WithCtx() to pass the context inline.
77-
ctx := context.Background()
78-
logger := sentry.NewLogger(ctx)
79-
80-
// Or inline using WithCtx()
81-
newCtx := context.Background()
82-
// WithCtx() does not modify the original context attached on the logger.
83-
logger.Info().WithCtx(newCtx).Emit("context passed")
84-
85-
// You can use the logger like [fmt.Print]
86-
logger.Info().Emit("Hello ", "world!")
87-
// Or like [fmt.Printf]
88-
logger.Info().Emitf("Hello %v!", "world")
89-
}
90-
```
91-
92-
You can also pass additional permanent attributes to the logger via `SetAttributes`, or attach certain attributes to the `LogEntry` itself.
93-
These attributes do not persist after Emitting the `LogEntry`. All attributes will be searchable in the Logs UI.
94-
95-
```go
96-
logger.SetAttributes(
97-
attribute.Int("key.int", 42),
98-
attribute.Bool("key.boolean", true),
99-
attribute.Float64("key.float", 42.4),
100-
attribute.String("key.string", "string"),
101-
)
102-
logger.Warn().Emitf("I have params: %v and attributes", "example param")
103-
104-
// This entry would contain all attributes attached to the logger.
105-
// However, it's also possible to overwrite them.
106-
logger.Info().String("key.string", "newstring").Emit("overwriting key.string")
107-
```
108-
109-
Currently, the `attribute` API supports only these value types: `int`, `string`, `bool`, and `float`.
20+
<PlatformContent includePath="logs/usage" />
11021

11122
## Integrations
11223

113-
### Supported libraries
114-
- [Slog](/platforms/go/guides/slog)
115-
- [Logrus](/platforms/go/guides/logrus)
116-
117-
### `io.Writer` interface
24+
<PlatformContent includePath="logs/integrations" />
11825

119-
The `sentry.Logger` implements the `io.Writer` interface, so you can easily inject the logger into your existing setup. However, to correctly
120-
link your traces you would need to create a new logger everytime you want to pass a new context. Due to this limitation we recommend using the
121-
`sentry.Logger` or any of the other supported integrations.
26+
## Options
12227

123-
```go
124-
sentryLogger := sentry.NewLogger(ctx)
125-
logger := log.New(sentryLogger, "", log.LstdFlags)
126-
logger.Println("Implementing log.Logger")
127-
```
28+
<PlatformContent includePath="logs/options" />
12829

12930
### Debug
13031

13132
If the `Debug` init option is set to true, calls to the `sentry.Logger` will also print to the console with the appropriate log level.
13233

133-
<Include name="logs/go-ctx-usage-alert.mdx"/>
34+
<Include name="logs/go-ctx-usage-alert.mdx" />
35+
36+
## Default Attributes
37+
38+
<PlatformContent includePath="logs/default-attributes" />

‎docs/platforms/java/common/logs/index.mdx‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@ description: "Structured logs allow you to send, view and query logs sent from y
55
sidebar_order: 5755
66
---
77

8-
98
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.
109

1110
## Requirements
@@ -27,3 +26,7 @@ With Sentry Structured Logs, you can send text-based log information from your a
2726
## Options
2827

2928
<PlatformContent includePath="logs/options" />
29+
30+
## Default Attributes
31+
32+
<PlatformContent includePath="logs/default-attributes" />

‎docs/platforms/javascript/common/logs/index.mdx‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,6 @@ notSupported:
1010

1111
<PlatformContent includePath="llm-rules-logs" />
1212

13-
1413
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.
1514

1615
## Requirements
@@ -32,3 +31,7 @@ With Sentry Structured Logs, you can send text-based log information from your a
3231
## Options
3332

3433
<PlatformContent includePath="logs/options" />
34+
35+
## Default Attributes
36+
37+
<PlatformContent includePath="logs/default-attributes" />

‎docs/platforms/php/common/logs/index.mdx‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@ description: "Structured logs allow you to send, view and query logs sent from y
55
sidebar_order: 5600
66
---
77

8-
98
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.
109

1110
<Alert title="Looking for Symfony?">
@@ -29,3 +28,7 @@ Let us know what you would like to see on GitHub: [Symfony Logs](https://github.
2928
## Options
3029

3130
<PlatformContent includePath="logs/options" />
31+
32+
## Default Attributes
33+
34+
<PlatformContent includePath="logs/default-attributes" />

‎docs/platforms/php/guides/laravel/logs/index.mdx‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@ description: "Structured logs allow you to send, view and query logs sent from y
55
sidebar_order: 5600
66
---
77

8-
98
With Sentry Structured Logs, you can send text-based log information from your Laravel applications to Sentry. Once in Sentry, these logs can be viewed alongside relevant errors, searched by text-string, or searched using their individual attributes.
109

1110
## Requirements
@@ -24,6 +23,10 @@ With Sentry Structured Logs, you can send text-based log information from your L
2423

2524
<PlatformContent includePath="logs/options" />
2625

26+
## Default Attributes
27+
28+
<PlatformContent includePath="logs/default-attributes" />
29+
2730
## Troubleshooting
2831

2932
If your logs are not appearing in Sentry, check or test the following:

0 commit comments

Comments
 (0)