Skip to content

Commit

Permalink
Merge branch 'master' into martinhaintz/fix-flutter-multiview
Browse files Browse the repository at this point in the history
* master: (39 commits)
  getsentry/relay@403f2bf
  feat(native): add backend trade-offs to Advanced Usage (#11721)
  🔧 chore(api): add additional troubleshooting instructions to publish api docs (#11772)
  Bump API schema to 02adb960 (#11773)
  Update metric-alert-config.mdx (#11760)
  update w-9 tax form (#11764)
  chore: silence fetch cache error due to size limit (#11767)
  fix Ureal engine DSN placeholder (#11769)
  feat: Banner pathname regex (#11761)
  docs(nuxt): Add troubleshoot pnpm (#11720)
  Docker Desktop to Colima fix (#11752)
  Bump API schema to d51784a6 (#11759)
  ref(feedback): update user feedback docs to include external issue linking & auto issue creation (#11729)
  getsentry/relay@d23c39a
  Changed /store to /envelope (because /store does not exist anymore (#11755)
  Refactor arcade embeds (#11722)
  feat(js): Add `skipBrowserExtensionCheck` documentation (#11693)
  getsentry/relay@a7d9096
  fix mermaid charts in dark mode (#11754)
  fix: Log4j configurations and wording (#11395)
  ...
  • Loading branch information
mar-hai committed Nov 11, 2024
2 parents 06c2123 + 3711dd8 commit 05f8102
Show file tree
Hide file tree
Showing 83 changed files with 1,168 additions and 821 deletions.
51 changes: 49 additions & 2 deletions .github/labels.yml
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,16 @@
color: F6F6F8
description: Pull requests that update a dependency file

# Issue types
- name: 'Type: Content'
color: FBCA04
- name: 'Type: Platform'
color: 1D76DB

#
- name: 'Develop'
color: F6F6F8

# Impacts
- name: 'Impact: Large'
color: C83852
Expand All @@ -32,6 +42,8 @@
color: '584774'
- name: 'Platform: Capacitor'
color: '584774'
- name: 'Platform: CLI'
color: '584774'
- name: 'Platform: Cocoa'
color: '584774'
- name: 'Platform: Cordova'
Expand All @@ -40,14 +52,20 @@
color: '584774'
- name: 'Platform: Elixir'
color: '584774'
- name: 'Platform: Flutter'
color: '584774'
- name: 'Platform: Go'
color: '584774'
- name: 'Platform: iOS'
color: '584774'
- name: 'Platform: Java'
color: '584774'
- name: 'Platform: JavaScript'
color: '584774'
- name: 'Platform: KMP'
color: '584774'
- name: 'Platform: Native'
color: '584774'
- name: 'Platform: PHP'
color: '584774'
- name: 'Platform: Python'
Expand All @@ -67,6 +85,7 @@
- name: 'Platform: Xamarin'
color: '584774'


# Waiting for Labels
- name: 'Waiting for: Support'
color: '8D5494'
Expand All @@ -80,7 +99,7 @@
# Product Areas - www.notion.so/sentry/473791bae5bf43399d46093050b77bf0
- name: 'Product Area: Unknown'
color: '8D5494'
- name: 'Product Area: Go to Sentry'
- name: 'Product Area: Sign In'
color: '8D5494'
- name: 'Product Area: Issues'
color: '8D5494'
Expand Down Expand Up @@ -217,16 +236,36 @@
- name: 'Team: Web Frontend'
color: 8D5494
description: team-web-sdk-frontend
- name: 'Team: Web Frontend SDKs'
color: 8D5494
description: team-web-sdk-frontend
- name: 'Team: Web SDK Backend'
color: 8D5494
description: team-web-sdk-backend
- name: 'Team: Web Backend SDKs'
color: 8D5494
description: team-web-sdk-backend
- name: 'Team: Workflow'
color: 8D5494
- name: 'All SDKs'
color: 1D76DB
- name: 'SDKs'
color: 1D76DB
- name: 'Develop'
color: 8D5494
- name: 'Do not merge'
color: 8D5494
- name: 'Improvement'
color: 8D5494
- name: 'Launch 🚀'
color: 8D5494
- name: 'Product'
color: 8D5494

# Miscellaneous
- name: API Docs
color: 649B42
- name: bug
- name: Bug
color: F6F6F8
- name: Common content
color: B0E299
Expand Down Expand Up @@ -279,3 +318,11 @@
color: F6F6F8
- name: release health
color: F6F6F8
- name: submodules
color: F6F6F8
- name: '404'
color: F6F6F8
- name: darkmode
color: F6F6F8
- name: github_actions
color: F6F6F8
4 changes: 2 additions & 2 deletions develop-docs/application/architecture.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Edges represent service dependencies.
```mermaid
graph TD
app[Your Application] --> |SDK| lb{{Load Balancer}}
lb --> |"sentry.example.com/api/\d+/store/"| relay
lb --> |"sentry.example.com/api/0/envelope/"| relay
lb --> |"sentry.example.com"| sentry_web["Sentry (web)"]
symbolicator --> sentry_web
relay --> kafka
Expand Down Expand Up @@ -50,7 +50,7 @@ For more information read [Path of an event through Relay](https://getsentry.git
```mermaid
graph TD
app[Your application] --> |sends crashes| lb{{nginx}}
lb --> |/api/n/store/| relay
lb --> |/api/0/envelope/| relay
relay --> kafka[(Ingest Kafka)]
kafka --> ingest-consumer["Sentry ingest consumer"]
ingest-consumer --> preprocess-event
Expand Down
24 changes: 24 additions & 0 deletions develop-docs/backend/api/public.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -483,6 +483,30 @@ NOTE: The `openapi-diff` test is supposed to fail when CI runs on your pull requ
---
**Problem**: `drf_spectacular.plumbing.UnableToProceedError' <class 'serializer_path.FooSerializer'> ... raise UnableToProceedError(hint)`
**Solution**: Check that the response of your API documentation is using a TypedDict rather than a serializer.
If the schema looks something like this:
```python
...
200: inline_sentry_response_serializer(
"ListDocIntegrationResponse", list[FooSerializer]
),
```
Then you need to change it to use a TypedDict by first typing the serializer, then updating the schema to use the TypedDict:
```python
...
200: inline_sentry_response_serializer(
"ListDocIntegrationResponse", list[FooSerializerResponse]
),
```
Refer to the section above on [Success Responses](#success-responses) for more information.
---
## Requesting an API to be public
Are you a Sentry user who wants an endpoint to be public?
Expand Down
6 changes: 6 additions & 0 deletions develop-docs/development/environment/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -288,3 +288,9 @@ docker ps
**Problem:** You use an Android emulator with a DSN pointing to localhost, and the events don't show up in your local Sentry instance.

**Solution:** Change `localhost` to `10.0.2.2`. So, for example, change http://d895df97e1cb4a33b4dff8af3e78da09@localhost:8000/2 to http://[email protected]:8000/2. This is because localhost or `127.0.0.1` refers to the emulator's own loopback interface, not the loopback interface of the host machine. For more information see https://developer.android.com/studio/run/emulator-networking.

---

**Problem:** Switching from Docker Desktop to Colima results in error `Failed to start service: Credentials store error: StoreError('docker-credential-desktop not installed or not available in PATH')`

**Solution:** Remove the `credsStore` key in your `~/.docker/config.json` file.
2 changes: 1 addition & 1 deletion develop-docs/sdk/data-model/envelope-items.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -272,7 +272,7 @@ details.
**Constraints:**

- This Item may occur at most once per Envelope.
- This Item must be sent with a Replay Recording Item.
- This Item must be sent with a Replay Event Item.

**Envelope Headers:**

Expand Down
135 changes: 135 additions & 0 deletions develop-docs/sdk/telemetry/traces/tracing-without-performance.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
---
title: Tracing Without Performance
---

If Sentry SDKs are not configured for sending spans (or transactions), they should fall back to a mode where they still handle continuing and propagating traces.
Internally, we call this mode "Tracing without Performance", or "TwP" in short ([learn more why](#historical-context)).
TwP mode ensures that error events and other signals are still connected via a trace, even if users choose not to send spans or performance data.

## Behavior

Tracing without Performance is the default fallback behavior of SDKs, when users [don't specify any tracing options](#configuration).

This means that SDKs by default always:

- continue incoming traces
- attach `event.contexts.trace` context on events (e.g. errors, check-ins, replays)
- attach the `trace` envelope header to Sentry envelopes, populated from the dynamic sampling context
- propagate trace data (`sentry-trace`, `baggage`) via the usual channels (e.g. HTTP headers, `<meta>` HTML elements, etc), with the correct [sampling decision](#sampling-decision)

## Configuration

TwP is active by default if users don't specify sampling options that enable span collection and sending (i.e. [regular tracing](#enable-regular-tracing)).
For example, the following trivial SDK setup (note the absence of sampling options) enables TwP:

```JavaScript
Sentry.init({
dsn: "___PUBLIC_DSN___",
});
```

TwP mode is exited by configuring the SDK for [regular tracing](#enable-regular-tracing) or partially disabled by [opting out of trace propagation](#disable-trace-propagation).

<Alert>

Note that some SDKs like the JavaScript Browser SDK require additional integrations to enable tracing all together.
This is fine as long as there's a good reason why additional configuration is required (like keeping bundle size in check in JS).

</Alert>

### Enable Regular Tracing

As soon as users specify a tracing option in the SDK configuration, SDKs will use the normal tracing mode, which means collecting and sending spans (or transactions) in addition to continuing and propagating traces.

This can be achieved by specifying `tracesSampleRate` or `tracesSampler`, or any other equivalent option in the SDK configuration:

```js
Sentry.init({
dsn: "___PUBLIC_DSN___",
tracesSampleRate: 0.1,
// or
tracesSampler: () => {
/*...*/
},
});
```

It's important to note that setting `tracesSampleRate: 0` does not mean that we fall back to TwP mode but that sampling decisions are always negative and we propagate the trace with a negative sampling decision.

### Disable Trace Propagation

To opt out of further propagating a trace, users can pass an empty array (or language-equivalent parameter) to the [`tracePropagationTargets` option](/sdk/telemetry/traces/#tracepropagationtargets). This will prevent the SDK from propagating trace information any further.

```js
Sentry.init({
dsn: "___PUBLIC_DSN___",
tracePropagationTargets: [],
});
```

Note, that for incoming requests with trace headers, SDKs should still continue this trace, but not propagate it further downstream.

## Implementation

SDKs implementing TwP mode must adhere to the behavior described in this section.
Everything else (e.g. how to store the trace data and specific tracing options) is considered an implementation detail and can be implemented as needed.

### Continuing Incoming Traces

SDKs in TwP mode must continue incoming traces (e.g. from incoming HTTP requests) if available and attach the trace data of the continued trace to any events that are created during the lifetime of this trace.
Furthermore, they must propagate the continued trace as usual on all outgoing requests.
This means that continuing traces should work just like in the regular tracing mode (with spans).

At the time of writing this document, there is no way to opt out of continuing incoming traces in TwP mode, unless users manually start a new trace.

### Starting a New Trace

If an SDK in TwP mode doesn't receive an incoming trace, it should start a new trace.
In this case, the new trace is not sampled (as in, there is no sampling decision, neither positive nor negative).
Instead, the sampling decision is _deferred_ to the next downstream SDK.

This means that:

- the SDK must not include a sampled flag in the [`sentry-trace` header](../#header-sentry-trace), meaning the header has the format `<traceId>-<spanId>`.
More details on the [sampled flag](../#the-sampled-value).
- the [dynamic sampling context](https://develop.sentry.dev/sdk/telemetry/traces/dynamic-sampling-context/), propagated via `baggage` must not contain the `sentry-sampled` key.

### Attaching Trace Data to Events and Envelopes

Any event created by an SDK in TwP mode must include the [`trace` context](/sdk/event-payloads/contexts/#trace-context).
This context should contain the trace data of the current trace, if available, just like in regular tracing mode.

Furthermore, the [`trace` envelope header](/sdk/telemetry/traces/dynamic-sampling-context/#envelope-header) (populated from the dynamic sampling context) must be attached to any outgoing event envelope.

### Trace Duration and Storage

Traces in TwP mode should have the same duration as regular traces.
For example, a TwP trace for a backend server should generally last for the duration of one individual request.
This usually corresponds with the lifetime of an [isolation scope](/sdk/miscellaneous/hub_and_scope_refactoring/#scope) (or current scope created within the isolation scope).

SDKs in TwP mode must store trace data in a way that makes it possible for them to be attached to events and propagated to outgoing requests.
The exact storage mechanism is up to the SDK implementation, but we recommended using the same mechanism as for regular traces.
Usually this means storing the data on the scope in a field called `propagationContext` as [recommended here](/sdk/telemetry/traces/distributed-tracing/).

On a related note, the `propagationContext` should be populated with a random `traceId` and `spanId` if no incoming trace is present.
This—in combination with the [`sentry-trace` header specification](/sdk/telemetry/traces/#header-sentry-trace) requiring a `spanId`—has an important implication on the Sentry product:
A non-existing `spanId` will be propagated along with the trace and attached to events.
While not ideal, we accept this limitation as the Sentry product can and should handle non-existing (parent) spans anyway.

As in regular tracing mode, for SDKs starting a new trace, the [Dynamic Sampling Context](/sdk/telemetry/traces/dynamic-sampling-context/) should be lazily populated and frozen for the duration of the trace.
Given that no span is actually available in TwP mode, the DSC will not contain any keys related to spans (`transaction`, `sample_rate` or `sampled`).

In SDKs adapting OpenTelemetry's tracing capabilities ([POTel](/sdk/hub_and_scope_refactoring/#f-use-otel-for-performance-instrumentation-potel)), the TwP trace data could also be stored in a non-recording span.
For Example, the Node SDK also starts non-recording Otel spans in TwP mode and takes the trace data from them. In case no span is started (e.g. a node script without request handling), it falls back to the propagation context on the scope.
Note that in the case of using the non-recording span, the span is also not sampled, meaning the sampling decision must still be deferred [when starting a new Trace](#starting-a-new-trace).

## Historical Context

TwP mode was introduced after SDKs were already capable of sending spans and transactions. Before TwP, SDKs would only handle traces if span-sending was enabled. Otherwise, neither trace data would be attached to any events nor were traces propagated further downstream.

The primary motivation for TwP was to ensure that errors across application or service boundaries were still connected if they occurred in the same trace.

The name "Tracing without Performance" was chosen because at the time of introduction, we associated spans purely with performance monitoring.
Today, we associate spans with "Tracing" in general, and only (some of) the data from spans with Performance Monitoring.
This is why the name from today's perspective is a bit misleading.
As a mental model, think of TwP as "Trace propagation and continuation without Spans".
2 changes: 1 addition & 1 deletion docs/api/auth.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ You can create authentication tokens within Sentry by [creating an internal inte

Some API endpoints require an authentication token that's associated with your user account, rather than an authentication token from an internal integration. These auth tokens can be created within Sentry on the "User settings" page (**User settings > User Auth Tokens**) and assigned specific scopes.

The endpoints that require a user authentication token are specific to your user, such as [List Your Organizations](/api/organizations/list-your-organizations/).
The endpoints that require a user authentication token are specific to your user, such as [Retrieve an Organization](/api/organizations/retrieve-an-organization/).

## DSN Authentication

Expand Down
14 changes: 1 addition & 13 deletions docs/concepts/data-management/event-grouping/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -80,19 +80,7 @@ Stack trace rules can work as a combination of both SDK and project settings. As

You can see a fingerprint by opening an issue, clicking "{} View JSON", and finding the _fingerprint_ property in that file. If the default grouping was used, you'll see "default" written there. If a different grouping was used, you'll see the actual fingerprint value itself.

<div style={{"height":"0px","paddingBottom":"calc(56.88524590163935% + 41px)","position":"relative","width":"100%"}}>
<iframe
src="https://demo.arcade.software/8vE2p1OF0WRxjg7XN8HH?embed"
frameborder="0"
loading="lazy"
webkitallowfullscreen
mozallowfullscreen
allowfullscreen
allow="fullscreen;"
style={{"colorScheme":"light","height":"100%","left":"0px","position":"absolute","top":"0px","width":"100%"}}
title="View Issue Fingerprint"
></iframe>
</div>
<Arcade src="https://demo.arcade.software/8vE2p1OF0WRxjg7XN8HH?embed" />

## Transaction Grouping Algorithms

Expand Down
14 changes: 1 addition & 13 deletions docs/concepts/key-terms/environments/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -40,16 +40,4 @@ If a project is hidden, you won't see that environment in the environment select

Follow along with the interactive demo below to see how to hide and unhide environments.

<div style={{"height":"0px","paddingBottom":"calc(66.5403% + 41px)","position":"relative","width":"100%"}}>
<iframe
src="https://demo.arcade.software/GqXUGJBjoH5fOG5AMyLt?embed"
frameborder="0"
loading="lazy"
webkitallowfullscreen
mozallowfullscreen
allowfullscreen
allow="fullscreen;"
style={{"colorScheme":"light","height":"100%","left":"0px","position":"absolute","top":"0px","width":"100%"}}
title="Environments - Hide/show"
></iframe>
</div>
<Arcade src="https://demo.arcade.software/GqXUGJBjoH5fOG5AMyLt?embed" />
Loading

0 comments on commit 05f8102

Please sign in to comment.