Skip to content

Commit de180cd

Browse files
inventarSarahinventarSarah
committed
Merge branch 'master' of github.com:getsentry/sentry-docs into smi/quick-start/nuxt-manual
2 parents d1af03e + 1f9e14f commit de180cd

File tree

36 files changed

+372
-245
lines changed

36 files changed

+372
-245
lines changed

‎develop-docs/sdk/telemetry/spans/batch-processor.mdx‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
title: Batch Processor
3+
---
4+
5+
<Alert level="warning">
6+
🚧 This document is work in progress.
7+
</Alert>
8+
9+
<Alert>
10+
This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels.
11+
</Alert>
12+
13+
The BatchProcessor batches spans and logs into one envelope to reduce the number of HTTP requests. When an SDK implements span streaming or logs, it MUST use a BatchProcessor, which is similar to [OpenTelemetry's Batch Processor](https://github.com/open-telemetry/opentelemetry-collector/blob/main/processor/batchprocessor/README.md). The BatchProcessor holds logs and finished spans in memory and batches them together into envelopes. It uses a combination of time and size-based batching. When writing this, the BatchProcessor only handles spans and logs, but an SDK MAY use it for other telemetry data in the future.
14+
15+
## Specification
16+
17+
Whenever the SDK finishes a span or captures a log, it MUST put it into the BatchProcessor. The SDK MUST NOT put unfinished spans into the BatchProcessor.
18+
19+
The BatchProcessor MUST start a timeout of 5 seconds when the SDK adds the first span or log. When the timeout exceeds, the BatchProcessor MUST send all spans or logs, no matter how many items it contains. The SDK MAY choose a different value for the timeout, but it MUST NOT exceed 30 seconds, as this can lead to problems with the span buffer on the backend, which uses a time interval of 60 seconds for determining segments for spans.
20+
21+
The BatchProcessor MUST send all items after the SDK when containing spans or logs exceeding 1MiB in size. The SDK MAY choose a different value for the max batch size keeping the [envelope max sizes](/sdk/data-model/envelopes/#size-limits) in mind. The SDK MUST calculate the size of a span or a log to manage the BatchProcessor's memory footprint. The SDK MUST serialize the span or log and calculate the size based on the serialized JSON bytes. As serialization is expensive, the BatchProcessor SHOULD keep track of the serialized spans and logs and pass these to the envelope to avoid serializing multiple times.
22+
23+
When the BatchProcessor sends all spans or logs, it MUST reset its timeout and remove all spans and logs. The SDK MUST apply filtering and sampling before adding spans or logs to the BatchProcessor. The SDK MUST apply rate limits to spans and logs after they leave the BatchProcessor to send as much data as possible by dropping data as late as possible.
24+
25+
The detailed specification is written in the [Gherkin syntax](https://cucumber.io/docs/gherkin/reference/). The specification uses spans as an example, but the same applies to logs or any other future telemetry data.
26+
27+
28+
```Gherkin
29+
Scenario: No spans in BatchProcessor 1 span added
30+
Given no spans in the BatchProcessor
31+
When the SDK finishes 1 span
32+
Then the SDK puts this span to the BatchProcessor
33+
And starts a timeout of 5 seconds
34+
And doesn't send the span to Sentry
35+
36+
Scenario: Span added before timeout exceeds
37+
Given span A in the BatchProcessor
38+
Given 4.9 seconds pass
39+
When the SDK finishes span B
40+
Then the SDK adds span B to the BatchProcessor
41+
And doesn't reset the timeout
42+
And doesn't send the spans A and B in the BatchProcessor to Sentry
43+
44+
Scenario: Spans with size of 1 MiB - 1 byte added, timeout exceeds
45+
Given spans with size of 1 MiB - 1 byte in the BatchProcessor
46+
When the timeout exceeds
47+
Then the SDK adds all the spans to one envelope
48+
And sends them to Sentry
49+
And resets the timeout
50+
And clears the BatchProcessor
51+
52+
Scenario: Spans with size of 1 MiB - 1 byte added within 4.9 seconds
53+
Given spans with size of 1 MiB - 1 byte in the BatchProcessor
54+
When the SDK finishes another span and puts it into the BatchProcessor
55+
Then the BatchProcessor puts all spans into one envelope
56+
And sends the envelope to Sentry
57+
And resets the timeout
58+
And clears the BatchProcessor
59+
60+
Scenario: Unfinished spans
61+
Given no span is in the BatchProcessor
62+
When the SDK starts a span but doesn't finish it
63+
Then the BatchProcessor is empty
64+
65+
Scenario: Span filtered out
66+
Given no span is in the BatchProcessor
67+
When the finishes a span
68+
And the span is filtered out
69+
Then the BatchProcessor is empty
70+
71+
Scenario: Span not sampled
72+
Given no span is in the BatchProcessor
73+
When the finishes a span
74+
And the span is not sampled
75+
Then the BatchProcessor is empty
76+
77+
Scenario: 1 span added application crashes
78+
Given 1 span in the SpansAggregator
79+
When the SDK detects a crash
80+
Then the SDK does nothing with the items in the BatchProcessor
81+
And loses the spans in the BatchProcessor
82+
83+
```

‎develop-docs/self-hosted/troubleshooting/docker.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@ sidebar_title: Docker
44
sidebar_order: 3
55
---
66

7+
## `FAIL: Docker Compose is required to run self-hosted` error but Docker Compose is installed
8+
9+
Around version 25.1.0 to 25.4.0, users which did not have `docker compose` plugin installed, and relied only on `docker-compose` will face some issues. Notably for Amazon Linux 2023 distro that does not have `docker-compose-plugin` packaged, you may need to install the standalone `docker-compose` separately. See [docker/compose installation guide](https://github.com/docker/compose?tab=readme-ov-file#linux) for more details.
10+
711
## Container Healthcheck
812

913
There may be some circumstances which you may want to increase or decrease healthcheck interval, timeout or retries for your custom needs. This can be achieved by editing `HEALTHCHECK_INTERVAL`, `HEALTHCHECK_TIMEOUT`, `HEALTHCHECK_RETRIES` variables' values in `.env`.

‎docs/platforms/go/common/tracing/instrumentation/custom-instrumentation/index.mdx‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,94 @@ To capture transactions and spans customized to your organization's needs, you m
1515
<PlatformContent includePath="performance/add-spans-example" />
1616

1717
<PlatformContent includePath="performance/retrieve-transaction" />
18+
19+
## Adding Span & Transaction Data Attributes
20+
21+
You can capture data attributes along with your spans and transactions. You can specify data attributes when starting a span or transaction:
22+
23+
```go
24+
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
25+
ctx := r.Context()
26+
27+
options := []sentry.SpanOption{
28+
// Set the OP based on values from https://develop.sentry.dev/sdk/performance/span-operations/
29+
sentry.WithOpName("http.server"),
30+
sentry.ContinueFromRequest(r),
31+
sentry.WithTransactionSource(sentry.SourceURL),
32+
}
33+
34+
// Create a transaction and assign data attributes
35+
transaction := sentry.StartTransaction(ctx,
36+
fmt.Sprintf("%s %s", r.Method, r.URL.Path),
37+
options...,
38+
)
39+
transaction.SetData("dataAttr1", 42)
40+
transaction.SetData("dataAttr2", true)
41+
// omitted code ...
42+
transaction.Finish()
43+
44+
// ... or create a span and assign data attributes
45+
span := sentry.StartSpan(ctx, "span1")
46+
span.SetData("dataAttr1", 42)
47+
span.SetData("dataAttr2", true)
48+
// omitted code ...
49+
span.Finish()
50+
})
51+
```
52+
53+
Or you can add data attributes to an existing transaction or span:
54+
55+
```go
56+
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
57+
ctx := r.Context()
58+
transaction := sentry.TransactionFromContext(ctx)
59+
60+
if transaction != nil {
61+
transaction.SetData("dataAttr1", 42)
62+
transaction.SetData("dataAttr2", true)
63+
}
64+
65+
span := sentry.SpanFromContext(ctx)
66+
span.SetData("dataAttr1", 42)
67+
span.SetData("dataAttr2", true)
68+
})
69+
```
70+
71+
Or you can update existing transaction and span data by:
72+
73+
```go
74+
if d, found := transaction.Data["dataAttr1"]; found {
75+
if dataAttr1, ok := d.(int); ok {
76+
transaction.SetData("dataAttr1", dataAttr1.(int)+42)
77+
}
78+
}
79+
80+
if d, found := span.Data["dataAttr1"]; found {
81+
if dataAttr1, ok := d.(int); ok {
82+
span.SetData("dataAttr1", dataAttr1.(int)+42)
83+
}
84+
}
85+
})
86+
```
87+
88+
To attach data attributes to the transaction and all its spans, you can use `BeforeSendTransaction`:
89+
90+
```go
91+
sentry.Init(sentry.ClientOptions{
92+
Dsn: "___PUBLIC_DSN___",
93+
BeforeSendTransaction: func(event *sentry.Event, hint *sentry.EventHint) *sentry.Event {
94+
for _, sp := range event.Spans {
95+
sp.SetData("dataAttr1", 42)
96+
sp.SetData("dataAttr2", true)
97+
}
98+
99+
dataCtx, ok := event.Contexts["trace"]["data"].(map[string]any)
100+
if !ok {
101+
dataCtx = make(map[string]any)
102+
event.Contexts["trace"]["data"] = dataCtx
103+
}
104+
dataCtx["num"] = 42
105+
return event
106+
},
107+
})
108+
```

‎docs/platforms/godot/configuration/options.mdx‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,10 +22,18 @@ Learn more about [DSN utilization](/product/sentry-basics/dsn-explainer/#dsn-uti
2222

2323
<ConfigKey name="debug">
2424

25-
Turns debug mode on or off. If `debug` is enabled, the SDK will print useful debugging information to standard output. These messages do not appear in the Godot console or log file but can be seen when launching Godot application from a terminal. It's generally not recommended to turn it on in production, though turning `debug` mode on will not cause any safety concerns.
25+
Turns debug mode on or off. If `debug` is enabled, the SDK will print useful debugging information. You can see it in the Output panel of the Godot editor. It's generally not recommended to turn it on in production, though turning `debug` mode on will not cause any safety concerns.
2626

2727
In the Project Settings, this option appears as `Debug Printing` and defaults to `Auto`. When set to `Auto`, the `debug` is enabled in debug builds (such as the editor and debug exports), and disabled in release export.
2828

29+
You can control the verbosity using the `diagnostic_level` option.
30+
31+
</ConfigKey>
32+
33+
<ConfigKey name="diagnostic_level">
34+
35+
Specifies the minimum level of messages to be printed if `debug` is turned on.
36+
2937
</ConfigKey>
3038

3139
<ConfigKey name="release">

‎docs/platforms/javascript/common/best-practices/index.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Special Use Cases
33
description: "Learn how to set up Sentry for several specific use cases with these best practice guides."
4-
sidebar_order: 6
4+
sidebar_order: 8000
55
notSupported:
66
- javascript.node
77
- javascript.aws-lambda

‎docs/platforms/javascript/common/configuration/filtering.mdx‎

Lines changed: 56 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -20,56 +20,15 @@ You can use the <PlatformIdentifier name="ignore-errors" /> option to filter out
2020

2121
<PlatformContent includePath="configuration/ignore-errors" />
2222

23+
See <PlatformLink to="/configuration/options/#ignoreErrors">ignoreErrors</PlatformLink> for details.
24+
2325
### Using <PlatformIdentifier name="before-send" />
2426

25-
You can configure a <PlatformIdentifier name="before-send" /> callback method to filter error events. Because it's called immediately before the event is sent to the server, this is your last chance to decide not to send data or to edit it. <PlatformIdentifier name="before-send" /> receives the event object as a parameter and, based on custom logic and the data available on the event, you can either modify the event’s data or drop it completely by returning `null`.
27+
You can configure a <PlatformIdentifier name="before-send" /> callback method to filter error events. Because it's called immediately before the event is sent to the server, this is your last chance to decide not to send data or to edit it. <PlatformIdentifier name="before-send" /> receives the event object as a parameter and, based on custom logic and the data available on the event, you can either modify the event’s data or drop it completely by returning `null`. This hook is called for both error and message events.
2628

2729
<PlatformContent includePath="configuration/before-send/" />
2830

29-
Note also that breadcrumbs can be filtered, as discussed in [our Breadcrumbs documentation](/product/error-monitoring/breadcrumbs/).
30-
31-
#### Event Hints
32-
33-
The <PlatformIdentifier name="before-send" /> callback is passed both the `event` and a second argument, `hint`, that holds one or more hints.
34-
35-
Typically, a `hint` holds the original exception so that additional data can be extracted or grouping is affected. In this example, the fingerprint is forced to a common value if an exception of a certain type has been caught:
36-
37-
<PlatformContent includePath="configuration/before-send-hint" />
38-
39-
When the SDK creates an event or breadcrumb for transmission, that transmission is typically created from some sort of source object. For instance, an error event is typically created from a log record or exception instance. For better customization, SDKs send these objects to certain callbacks (<PlatformIdentifier name="before-send" />, <PlatformIdentifier name="before-breadcrumb" /> or the event processor system in the SDK).
40-
41-
### Using Hints
42-
43-
Hints are available in two places:
44-
45-
1. <PlatformIdentifier name="before-send" /> / <PlatformIdentifier name="before-breadcrumb" />
46-
2. `eventProcessors`
47-
48-
Event and breadcrumb `hints` are objects containing various information used to put together an event or a breadcrumb. Typically `hints` hold the original exception so that additional data can be extracted or grouping can be affected.
49-
50-
For events, hints contain properties such as `event_id`, `originalException`, `syntheticException` (used internally to generate cleaner stack trace), and any other arbitrary `data` that you attach.
51-
52-
For breadcrumbs, the use of `hints` is implementation dependent. For XHR requests, the hint contains the xhr object itself; for user interactions the hint contains the DOM element and event name and so forth.
53-
54-
<PlatformContent includePath="configuration/before-send-fingerprint">
55-
56-
In this example, the fingerprint is forced to a common value if an exception of a certain type has been caught:
57-
58-
</PlatformContent>
59-
60-
#### Hints for Events
61-
62-
`originalException`
63-
64-
The original exception that caused the Sentry SDK to create the event. This is useful for changing how the Sentry SDK groups events or to extract additional information.
65-
66-
`syntheticException`
67-
68-
When a string or a non-error object is raised, Sentry creates a synthetic exception so you can get a basic stack trace. This exception is stored here for further data extraction.
69-
70-
#### Hints for Breadcrumbs
71-
72-
<PlatformContent includePath="configuration/breadcrumb-hints" />
31+
See <PlatformLink to="/configuration/options/#beforeSend">beforeSend</PlatformLink> for details, and [Using Hints](#using-hints) for details on the `hint` object.
7332

7433
### Using `allowUrls` and `denyUrls`
7534

@@ -83,6 +42,9 @@ Sentry.init({
8342

8443
You can also use `denyUrls` if you want to block errors created on specific URLs from being sent to Sentry.
8544

45+
- See <PlatformLink to="/configuration/options/#allowUrls">allowUrls</PlatformLink> details
46+
- See <PlatformLink to="/configuration/options/#denyUrls">denyUrls</PlatformLink> details
47+
8648
### Using `thirdPartyErrorFilterIntegration`
8749

8850
_Available in browser-based SDKs from version 8.10.0_
@@ -156,28 +118,67 @@ You can use the <PlatformIdentifier name="ignore-transactions" /> option to filt
156118

157119
<PlatformContent includePath="configuration/ignore-transactions" />
158120

159-
### Using <PlatformIdentifier name="traces-sampler" />
160-
161-
**Note:** The <PlatformIdentifier name="traces-sampler" /> and <PlatformIdentifier name="traces-sample-rate" /> config options are mutually exclusive. If you define a <PlatformIdentifier name="traces-sampler" /> to filter out certain transactions, you must also handle the case of non-filtered transactions by returning the rate at which you'd like them sampled.
121+
See <PlatformLink to="/configuration/options/#ignoreTransactions">ignoreTransactions</PlatformLink> for details.
162122

163-
In its simplest form, used just for filtering the transaction, it looks like this:
164-
165-
<PlatformContent includePath="performance/traces-sampler-as-filter" />
166-
167-
It also allows you to sample different transactions at different rates.
123+
### Using <PlatformIdentifier name="traces-sampler" />
168124

169-
If the transaction currently being processed has a parent transaction (from an upstream service calling this service), the parent (upstream) sampling decision will always be included in the sampling context data, so that your <PlatformIdentifier name="traces-sampler" /> can choose whether and when to inherit that decision. In most cases, inheritance is the right choice, to avoid breaking distributed traces. A broken trace will not include all your services. See <PlatformLink to="/configuration/sampling/#inheritance">Inheriting the parent sampling decision</PlatformLink> to learn more.
125+
You can also use the <PlatformLink to="/configuration/options/#tracesSampler">tracesSampler</PlatformLink> option to prevent certain transactions from being reported to Sentry.
170126

171-
Learn more about <PlatformLink to="/configuration/sampling/">configuring the sample rate</PlatformLink>.
127+
See <PlatformLink to="/configuration/sampling/#setting-a-sampling-function">Sampling</PlatformLink> on information about how to use it.
172128

173129
### Using `beforeSendTransaction`
174130

175131
<PlatformContent includePath="configuration/before-send-transaction" />
176132

133+
See <PlatformLink to="/configuration/options/#beforeSendTransaction">beforeSendTransaction</PlatformLink> for details, and [Using Hints](#using-hints) for details on the `hint` object.
134+
177135
## Filtering Spans
178136

179137
Use the <PlatformIdentifier name="before-send-span" /> configuration option which allows you to provide a function to modify a span.
180138
This function is called for the root span and all child spans. If you want to drop the root span, including its child spans, use [`beforeSendTransaction`](#using-beforesendtransaction) instead.
181139
Please note that you cannot use `beforeSendSpan` to drop a span, you can only modify it and filter data on it.
182140

183141
<PlatformContent includePath="configuration/before-send-span" />
142+
143+
See <PlatformLink to="/configuration/options/#beforeSendSpan">beforeSendSpan</PlatformLink> for details.
144+
145+
## Filtering Breadcrumbs
146+
147+
You can filter breadcrumbs by using the `beforeBreadcrumb` configuration option:
148+
149+
<PlatformContent includePath="enriching-events/breadcrumbs/before-breadcrumb" />
150+
151+
See <PlatformLink to="/configuration/options/#beforeBreadcrumb">beforeBreadcrumb</PlatformLink> for details.
152+
153+
## Using Hints
154+
155+
Hints are available in two places:
156+
157+
1. <PlatformIdentifier name="before-send" /> / <PlatformIdentifier name="before-breadcrumb" />
158+
2. Event processors added via `Sentry.addEventProcessor()`
159+
160+
Event and breadcrumb `hints` are objects containing various types of information used to put together an event or a breadcrumb. Typically `hints` hold the original exception so that additional data can be extracted or grouping can be affected.
161+
162+
For events, hints contain properties such as `event_id`, `originalException`, `syntheticException` (used internally to generate cleaner stack trace), and any other arbitrary `data` that you attach.
163+
164+
For breadcrumbs, the use of `hints` is implementation dependent. For XHR requests, the hint contains the xhr object itself; for user interactions the hint contains the DOM element and event name and so forth.
165+
166+
<PlatformContent includePath="configuration/before-send-fingerprint">
167+
168+
In this example, the fingerprint is forced to a common value if an exception of a certain type has been caught:
169+
170+
</PlatformContent>
171+
172+
### Hints for Events
173+
174+
`originalException`
175+
176+
The original exception that caused the Sentry SDK to create the event. This is useful for changing how the Sentry SDK groups events or to extract additional information.
177+
178+
`syntheticException`
179+
180+
When a string or a non-error object is raised, Sentry creates a synthetic exception so you can get a basic stack trace. This exception is stored here for further data extraction.
181+
182+
### Hints for Breadcrumbs
183+
184+
<PlatformContent includePath="configuration/breadcrumb-hints" />

0 commit comments

Comments
 (0)