Skip to content

Commit 9a2a473

Browse files
giortzisggiortzisg
committed
restructure Go docs
1 parent 381c26e commit 9a2a473

File tree

4 files changed

+204
-255
lines changed

4 files changed

+204
-255
lines changed

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

Lines changed: 73 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -11,149 +11,128 @@ With Sentry Structured Logs, you can send text based log information from your a
1111

1212
## Requirements
1313

14-
Logs in Go are supported in Sentry Go SDK version `0.33.0` and above.
14+
Logs in Go are supported in Sentry Go SDK version `0.33.0` and above. For using integrations of other log libraries, have a look at each specific page for more details on requirements.
1515

1616
## Setup
1717

1818
To enable logging, you need to initialize the SDK with the `EnableLogs` option set to true.
1919

2020
```go
21-
package main
22-
23-
import (
24-
"context"
25-
"github.com/getsentry/sentry-go"
26-
"time"
27-
)
28-
29-
func main() {
30-
if err := sentry.Init(sentry.ClientOptions{
21+
sentry.Init(sentry.ClientOptions{
3122
Dsn: "___PUBLIC_DSN___",
23+
// Enable logs to be sent to Sentry
3224
EnableLogs: true,
33-
}); err != nil {
34-
fmt.Printf("Sentry initialization failed: %v\n", err)
35-
}
36-
// Flush buffered events before the program terminates.
37-
// Set the timeout to the maximum duration the program can afford to wait.
38-
defer sentry.Flush(2 * time.Second)
39-
}
25+
})
4026
```
4127

4228
## Usage
4329

44-
Once the feature is enabled on the SDK and the SDK is initialized, you can send logs by using
45-
the `sentry.Logger` API.
46-
47-
The `Sentry.Logger` API exposes methods that support six different log levels: `trace`,
48-
`debug`, `info`, `warn`, `error` and `fatal`. The methods support both `fmt.Print` and `fmt.Printf` like syntax.
49-
If you pass in format specifiers like `%v`, these will be sent to Sentry, and can be searched from within the Logs UI,
50-
and even added to the Logs views as a dedicated column.
51-
52-
```go
53-
ctx := context.Background()
54-
logger := sentry.NewLogger(ctx)
30+
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.
5531

56-
// You can use the logger like [fmt.Print]
57-
logger.Info(ctx, "Hello ", "world!")
58-
// Or like [fmt.Printf]
59-
logger.Infof(ctx, "Hello %v!", "world")
60-
```
32+
The `sentry.Logger` API exposes methods that support six different log levels:
33+
- `trace`
34+
- `debug`
35+
- `info`
36+
- `warn`
37+
- `error`
38+
- `fatal`
6139

62-
You can also pass additional attributes to the logger via the `SetAttributes` function. These attributes will also be searchable in the Logs UI.
40+
The methods support both `fmt.Print` and `fmt.Printf` like syntax. If you pass in format specifiers like `%v`, these will be
41+
sent to Sentry, and can be searched from within the Logs UI, and even added to the Logs views as a dedicated column.
6342

6443
```go
65-
package main
66-
67-
import (
68-
"context"
69-
"github.com/getsentry/sentry-go"
70-
"github.com/getsentry/sentry-go/attribute"
71-
"time"
72-
)
73-
7444
func main() {
75-
err := sentry.Init(sentry.ClientOptions{
45+
if err := sentry.Init(sentry.ClientOptions{
7646
Dsn: "___PUBLIC_DSN___",
7747
EnableLogs: true,
78-
})
79-
if err != nil {
80-
panic(err)
48+
}); err != nil {
49+
log.Fatalf("Sentry initialization failed: %v", err)
8150
}
51+
// Flush buffered events before the program terminates.
52+
// Set the timeout to the maximum duration the program can afford to wait.
8253
defer sentry.Flush(2 * time.Second)
8354

55+
// The SentryLogger requires context, to link logs with the appropriate traces. You can either create a new logger
56+
// by providing the context, or use WithCtx() to pass the context inline.
8457
ctx := context.Background()
8558
logger := sentry.NewLogger(ctx)
8659

87-
logger.SetAttributes(
88-
attribute.Int("key.int", 42),
89-
attribute.Bool("key.boolean", true),
90-
attribute.Float64("key.float", 42.4),
91-
attribute.String("key.string", "string"),
92-
)
93-
logger.Warnf(ctx, "I have params: %v and attributes", "example param")
60+
// Or inline using WithCtx()
61+
newCtx := context.Background()
62+
// WithCtx() does not modify the original context attached on the logger.
63+
logger.Info().WithCtx(newCtx).Emit("context passed")
64+
65+
// You can use the logger like [fmt.Print]
66+
logger.Info().Emit("Hello ", "world!")
67+
// Or like [fmt.Printf]
68+
logger.Info().Emitf("Hello %v!", "world")
9469
}
9570
```
9671

97-
Currently the `attribute` API supports only these value types: `int`, `string`, `bool`, and `float`.
72+
You can also pass additional permanent attributes to the logger via `SetAttributes`, or attach certain attributes to the `LogEntry` itself.
73+
These attributes do not persist after Emitting the `LogEntry`. All attributes will be searchable in the Logs UI.
74+
75+
```go
76+
logger.SetAttributes(
77+
attribute.Int("key.int", 42),
78+
attribute.Bool("key.boolean", true),
79+
attribute.Float64("key.float", 42.4),
80+
attribute.String("key.string", "string"),
81+
)
82+
logger.Warn().Emitf("I have params: %v and attributes", "example param")
83+
84+
// This entry would contain all attributes attached to the logger.
85+
// However, it's also possible to overwrite them.
86+
logger.Info().String("key.string", "newstring").Emit("overwriting key.string")
87+
```
88+
89+
Currently, the `attribute` API supports only these value types: `int`, `string`, `bool`, and `float`.
9890

9991
## Integrations
10092

93+
### Supported libraries
94+
- [Slog](/platforms/go/guides/slog)
95+
- [Logrus](/platforms/go/guides/logrus)
96+
10197
### `io.Writer` interface
10298

103-
The `sentry.Logger` implements the `io.Writer` interface, so you can easily inject the logger into your existing setup.
99+
The `sentry.Logger` implements the `io.Writer` interface, so you can easily inject the logger into your existing setup. However, to correctly
100+
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
101+
`sentry.Logger` or any of the other supported integrations.
104102

105103
```go
106104
sentryLogger := sentry.NewLogger(ctx)
107105
logger := log.New(sentryLogger, "", log.LstdFlags)
108106
logger.Println("Implementing log.Logger")
109-
110-
slogger := slog.New(slog.NewJSONHandler(sentryLogger, nil))
111-
slogger.Info("Implementing slog.Logger")
112107
```
113108

114-
<Alert>
115-
In order to properly attach the correct trace with each Log entry, a
116-
`context.Context` is required. The `Write` function of the `io.Writer`
117-
interface doesn't provide `context`, so wrapping the custom logger will not
118-
get the trace and current span attached. We recommend using the
119-
`sentry.Logger` to ensure your logs are connected to spans and errors in the
120-
Sentry UI.
121-
</Alert>
122-
123-
### Integrations
124-
- [Slog](/platforms/go/guides/slog)
125-
- [Logrus](/platforms/go/guides/logrus)
126-
127-
### Upcoming Integrations
128-
129-
We're actively working on adding more integration support for Logs. Currently, we are looking at adding support for [`zerolog`](https://pkg.go.dev/github.com/rs/zerolog). You can follow this [GitHub issue](https://github.com/getsentry/sentry-go/issues/1015) to track progress.
130-
131109
## Options
132110

133111
### BeforeSendLog
134112

135113
To filter logs, or update them before they are sent to Sentry, you can use the `BeforeSendLog` client option.
136114

137115
```go
138-
if err := sentry.Init(sentry.ClientOptions{
139-
Dsn: "___PUBLIC_DSN___",
140-
EnableLogs: true,
141-
BeforeSendLog: func(log *Log) *Log {
142-
// filter out all trace logs
143-
if log.Level == sentry.LogLevelTrace {
144-
return nil
145-
}
146-
147-
// filter all logs below warning
148-
if log.Severity <= LogSeverityInfo {
149-
return nil
150-
}
151-
},
152-
}); err != nil {
153-
fmt.Printf("Sentry initialization failed: %v\n", err)
154-
}
116+
sentry.Init(sentry.ClientOptions{
117+
Dsn: "___PUBLIC_DSN___",
118+
EnableLogs: true,
119+
BeforeSendLog: func(log *sentry.Log) *sentry.Log {
120+
// filter out all trace logs
121+
if log.Level == sentry.LogLevelTrace {
122+
return nil
123+
}
124+
125+
// filter all logs below warning
126+
if log.Severity <= sentry.LogSeverityInfo {
127+
return nil
128+
}
129+
return log
130+
},
131+
})
155132
```
156133

157134
### Debug
158135

159136
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.
137+
138+
<Include name="logs/go-ctx-usage-alert.mdx"/>

‎docs/platforms/go/guides/logrus/index.mdx

Lines changed: 65 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -11,30 +11,34 @@ Go API documentation for the [`sentrylogrus` package](https://pkg.go.dev/github.
1111

1212
Logrus structured logging is supported in Sentry Go SDK version `0.34.0` and above.
1313

14-
## Install
14+
## Setup
1515

16+
Install the `sentrylogrus` package:
1617
```bash
1718
go get github.com/getsentry/sentry-go/logrus
1819
```
1920

20-
<Break />
21+
To enable logging, you need to initialize the SDK with the `EnableLogs` option set to true.
2122

22-
<SignInNote />
23+
```go
24+
sentry.Init(sentry.ClientOptions{
25+
Dsn: "___PUBLIC_DSN___",
26+
// Enable logs to be sent to Sentry
27+
EnableLogs: true,
28+
})
29+
```
30+
31+
## Configure
32+
33+
`sentrylogrus` provides two types of hooks to configure the integration with Sentry. Both hooks accept these options:
34+
- **Levels**: A slice of `logrus.Level` specifying which log levels to capture
35+
- **ClientOptions**: Standard `sentry.ClientOptions` for configuration
36+
37+
## Usage
2338

2439
To integrate Sentry with Logrus, you can set up both log hooks and event hooks to capture different types of data at various log levels.
2540

2641
```go
27-
import (
28-
"fmt"
29-
"net/http"
30-
"os"
31-
"time"
32-
33-
"github.com/sirupsen/logrus"
34-
"github.com/getsentry/sentry-go"
35-
sentrylogrus "github.com/getsentry/sentry-go/logrus"
36-
)
37-
3842
func main() {
3943
// Initialize Logrus
4044
logger := logrus.New()
@@ -111,37 +115,72 @@ func main() {
111115
}
112116
```
113117

114-
## Configure
115-
116-
`sentrylogrus` provides two types of hooks to configure the integration with Sentry. Both hooks accept these options:
117-
- **Levels**: A slice of `logrus.Level` specifying which log levels to capture
118-
- **ClientOptions**: Standard `sentry.ClientOptions` for configuration
119-
120118
### LogHook
121119

122-
Use `sentrylogrus.NewLogHook()` to send structured logs to Sentry. This hook captures log entries and sends them to Sentry's structured logging system.
120+
You have two ways to create a new `LogHook`. Either by using `sentrylogrus.NewLogHook()` and passing the `sentry.ClientOptions` or
121+
by using `sentrylogrus.NewLogHookFromClient()` and passing an already created `sentry.Client`. These hook captures log entries and
122+
send them to Sentry's structured logging system.
123123

124+
#### NewLogHook
124125
```go
125126
logHook, err := sentrylogrus.NewLogHook(
126127
[]logrus.Level{logrus.InfoLevel, logrus.WarnLevel},
127128
sentry.ClientOptions{
128129
Dsn: "___PUBLIC_DSN___",
129130
EnableLogs: true, // Required for log entries
130-
})
131+
},
132+
)
133+
```
134+
135+
#### NewLogHookFromClient
136+
137+
Use `NewLogHookFromClient` if you've already initialized the Sentry SDK.
138+
```go
139+
if err := sentry.Init(sentry.ClientOptions{
140+
Dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
141+
EnableLogs: true,
142+
}); err != nil {
143+
log.Fatalf("Sentry initialization failed: %v", err)
144+
}
145+
hub := sentry.CurrentHub()
146+
logHook := sentrylogrus.NewLogHookFromClient(
147+
[]logrus.Level{logrus.InfoLevel, logrus.WarnLevel},
148+
hub.Client(),
149+
)
131150
```
132151

133152
### EventHook
134153

135-
Use `sentrylogrus.NewEventHook()` to send log entries as Sentry events. This is useful for error tracking and alerting.
154+
You also have two ways to create a new `EventHook`. Either by using `sentrylogrus.NewEventHook()` and passing the `sentry.ClientOptions` or
155+
by using `sentrylogrus.NewEventFromClient()` and passing an already created `sentry.Client`. These hook captures log entries and
156+
send them as events. This is helpful for error tracking and alerting.
136157

158+
#### NewEventHook
137159
```go
138160
eventHook, err := sentrylogrus.NewEventHook(
139161
[]logrus.Level{logrus.ErrorLevel, logrus.FatalLevel, logrus.PanicLevel},
140162
sentry.ClientOptions{
141163
Dsn: "___PUBLIC_DSN___",
142164
Debug: true,
143165
AttachStacktrace: true,
144-
})
166+
},
167+
)
168+
```
169+
#### NewEventHookFromClient
170+
171+
Use `NewEventHookFromClient` if you've already initialized the Sentry SDK.
172+
```go
173+
if err := sentry.Init(sentry.ClientOptions{
174+
Dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
175+
EnableLogs: true,
176+
}); err != nil {
177+
log.Fatalf("Sentry initialization failed: %v", err)
178+
}
179+
hub := sentry.CurrentHub()
180+
eventHook := sentrylogrus.NewEventHookFromClient(
181+
[]logrus.Level{logrus.InfoLevel, logrus.WarnLevel},
182+
hub.Client(),
183+
)
145184
```
146185

147186
<Alert>
@@ -172,6 +211,8 @@ sentryHandler := sentryhttp.New(sentryhttp.Options{})
172211
http.Handle("/async", sentryHandler.Handle(http.HandlerFunc(myAsyncHandler)))
173212
```
174213

214+
<Include name="logs/go-ctx-usage-alert.mdx"/>
215+
175216
## Logs
176217

177218
For comprehensive logging setup with Logrus, including advanced configuration options and best practices, see the [Go Logs documentation](/platforms/go/logs/). The Logrus integration shown above provides seamless integration with Sentry's structured logging features.

0 commit comments

Comments
 (0)