Skip to content

Commit a38ff51

Browse files
jpnurmijpnurmi
committed
Merge remote-tracking branch 'origin/master' into jpnurmi/feat/native-metrics
2 parents 9e54304 + 3a2b23e commit a38ff51

208 files changed

Lines changed: 5206 additions & 2490 deletions

File tree

Some content is hidden

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

‎AGENTS.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,3 +63,12 @@ When writing requirements in `develop-docs/`:
6363
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.
6464
</Alert>
6565
```
66+
67+
## Plan Mode
68+
69+
- Make the plan extremely concise. Sacrifice grammar for the sake of concision.
70+
- At the end of each plan, give me a list of unresolved questions to answer, if any.
71+
72+
## Pull Request generation
73+
74+
Use .github/PULL_REQUEST_TEMPLATE.md and add Co-Authored-By: Claude

‎develop-docs/engineering-practices/ai-assisted-development.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -137,7 +137,7 @@ When a task spans multiple repositories, use `/add-dir` in Claude Code to add ad
137137

138138
### Managing Context
139139

140-
Long sessions accumulate irrelevant context that can degrade performance. Use `/clear` between unrelated tasks to reset the context window. Use `/compact` to summarize and condense the current conversation. Give sessions descriptive names so you can `/resume` them later.
140+
Long sessions accumulate irrelevant context that can degrade performance. Use `/clear` between unrelated tasks to reset the context window. Use `/compact` to condense the conversation, or `/compact [instructions]` to preserve specific information like core definitions or debugging notes. Give sessions descriptive names so you can `/resume` them later.
141141

142142
### Todo Lists
143143

‎develop-docs/sdk/data-model/envelope-items.mdx‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -260,12 +260,12 @@ Use this to explicitly link a related error in the feedback UI.
260260
: _UUID String, optional._ The identifier of a related Session Replay in the same
261261
project. Sentry uses this ID to render a Replay clip in the feedback UI.
262262

263-
**Attaching Screenshots:**
263+
**Attaching Files:**
264264

265-
You can associate screenshots with a feedback by sending image data as
265+
You can attach files of any type to a feedback (screenshots, logs, documents, etc.) by sending them as
266266
[attachment items](/sdk/data-model/envelope-items/#attachment), with `event_id`
267-
corresponding to the feedback item. We recommend sending the items in the same
268-
Envelope.
267+
corresponding to the feedback item. We recommend sending the attachment items in the same
268+
Envelope as the feedback item.
269269

270270
**Constraints:**
271271

‎develop-docs/sdk/expected-features/data-handling.mdx‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,12 @@ In the event that API returns data considered PII, we guard that behind a flag c
1313
This is an option in the SDK called [_send-default-pii_](https://docs.sentry.io/platforms/python/configuration/options/#send-default-pii)
1414
and is **disabled by default**. That means that data that is naturally sensitive is not sent by default.
1515

16+
<Alert level="info">
17+
18+
When a user manually sets the data on the scope (user, contexts, tags, data, request, response, etc.), this data should not be gated by the _Send Default PII_ flag and should always be attached to all outgoing telemetry. This also applies to the data that the user manually sets on a span, log, metric and other types of telemetry (directly or, for example, via `BeforeSend`).
19+
20+
</Alert>
21+
1622
Certain sensitive data must never be sent through SDK instrumentation, regardless of any configuration:
1723

1824
- HTTP Headers: The keys of known sensitive headers are added, while their values must be replaced with `"[Filtered]"`.
@@ -26,7 +32,6 @@ Some examples of data guarded by `send_default_pii: false`:
2632
- When attaching data of HTTP requests and/or responses to events
2733
- Request Body: "raw" HTTP bodies (bodies which cannot be parsed as JSON or FormData) are removed
2834
- HTTP Headers: header values, containing information about the user are replaced with `"[Filtered]"`
29-
- _Note_ that if a user explicitly sets a request on the scope, nothing is stripped from that request. The above rules only apply to integrations that come with the SDK.
3035
- User-specific information (e.g. the current user ID according to the used web-framework) is not collected and therefore not sent at all.
3136
- On desktop applications
3237
- The username logged in the device is not included. This is often a person's name.

‎develop-docs/sdk/expected-features/environment-variables.mdx‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
title: Environment Variables
3+
sidebar_order: 10
4+
description: >-
5+
Common environment variables that Sentry SDKs should support for configuration
6+
without code changes.
7+
---
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+
Sentry SDKs **SHOULD** support a set of common environment variables that allow users to configure SDK behavior without modifying their code. This is particularly useful for containerized deployments, serverless environments, or when users need to adjust settings without redeploying their application.
14+
15+
## Supported Environment Variables
16+
17+
The following environment variables **SHOULD** be supported across Sentry server-side SDKs:
18+
19+
| Variable | Description |
20+
|----------|-------------|
21+
| `SENTRY_DSN` | The Data Source Name that tells the SDK where to send events. |
22+
| `SENTRY_RELEASE` | The release version of the application. Used to associate events with source maps and track regressions. |
23+
| `SENTRY_ENVIRONMENT` | The environment name, such as `production`, `staging`, or `development`. |
24+
| `SENTRY_SAMPLE_RATE` | Controls the percentage of error events sent to Sentry (0.0 to 1.0). |
25+
| `SENTRY_TRACES_SAMPLE_RATE` | Controls the percentage of transactions sent for tracing (0.0 to 1.0). |
26+
| `SENTRY_PROFILES_SAMPLE_RATE` | Controls the percentage of transactions that include profiling data (0.0 to 1.0). Requires tracing to be enabled. |
27+
| `SENTRY_DEBUG` | Enables debug mode for troubleshooting SDK issues. |
28+
29+
SDKs **MAY** support additional SDK-specific environment variables beyond this common set. Any additional environment variables **SHOULD** be documented in the SDK's user-facing documentation.
30+
31+
<Alert>
32+
Some SDKs may also offer additional SDK-specific environment variables beyond this common set. Check the [platform-specific documentation](https://docs.sentry.io/platforms/) for the full list of supported options.
33+
</Alert>
34+
35+
## Precedence
36+
37+
When both environment variables and code-based configuration are present, **code-based configuration MUST take precedence**. If the user explicitly passes a value to the SDK's init function, the environment variable **MUST** be ignored.
38+
39+
To use environment variables, users omit the option from their init call and the SDK reads from the environment automatically:
40+
41+
```javascript
42+
// SDK will read from SENTRY_DSN automatically
43+
Sentry.init({
44+
// dsn omitted, will use SENTRY_DSN
45+
});
46+
```
47+
48+
```python
49+
import sentry_sdk
50+
51+
# SDK will read from SENTRY_DSN automatically
52+
sentry_sdk.init(
53+
# dsn omitted, will use SENTRY_DSN
54+
)
55+
```
56+
57+
```go
58+
import "github.com/getsentry/sentry-go"
59+
60+
// SDK will read from SENTRY_DSN automatically
61+
sentry.Init(sentry.ClientOptions{
62+
// Dsn omitted, will use SENTRY_DSN
63+
})
64+
```
65+
66+
```php
67+
\Sentry\init([
68+
// dsn omitted, will use SENTRY_DSN
69+
]);
70+
```
71+
72+
## Client-Side Considerations
73+
74+
Environment variables work differently in client-side environments like web browsers, where the concept of environment variables doesn't exist at runtime. For frontend SDKs, values **MUST** be injected by users at build time or configured directly in code.
75+
76+
For server-side SDKs (Node.js, Python, Ruby, Java, .NET, Go, PHP, etc.), environment variables are read at runtime when the SDK initializes.

‎develop-docs/sdk/expected-features/index.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,12 @@ Backend SDKs (typically used in server applications) should have backpressure ma
7777

7878
See <Link to="/sdk/telemetry/traces/backpressure/">Backpressure Management</Link> for details.
7979

80+
## Environment Variables
81+
82+
Server-side SDKs should support common environment variables for configuration without code changes, including `SENTRY_DSN`, `SENTRY_RELEASE`, `SENTRY_ENVIRONMENT`, and sample rate options.
83+
84+
See <Link to="/sdk/expected-features/environment-variables">Environment Variables</Link> for details.
85+
8086
## Debug Mode
8187

8288
Every SDK must implement a debug mode, which is disabled by default. Users can enable it by setting the option `debug` to `true`. If the debug mode is enabled, the SDK prints out useful debugging information for two main purposes:

‎develop-docs/sdk/platform-specifics/python-sdk/ci.mdx‎

Lines changed: 11 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,20 +4,19 @@ description: Our test setup and how our CI files are generated.
44
sidebar_order: 20
55
---
66

7-
The GitHub workflow files for testing specific integration groups (like AI, Web Frameworks, Databases, etc.) are generated by [this script](https://github.com/getsentry/sentry-python/blob/master/scripts/split-tox-gh-actions/split-tox-gh-actions.py). Essentially, the script scans our `tox.ini` and generates the group test CI YAML files in `.github/workflows`.
7+
Our test suite consists of a common part that tests basic SDK functionality, and an integrations part that tests individual integrations.
88

9-
There are multiple components to this:
10-
* `tox.ini` is where the configuration (what to test and what versions) is read from
11-
* `scripts/split-tox-gh-actions/split-tox-gh-actions.py` is the script that defines the [test groups](https://github.com/getsentry/sentry-python/blob/0f3e5db0c8aabcad0baf0e8b2d3e31e27e839b3e/scripts/split-tox-gh-actions/split-tox-gh-actions.py#L57) and generates the resulting YAML files
12-
* `scripts/split-tox-gh-actions/templates` contains the jinja2 template snippets used to generate the YAML files
13-
* `.github/workflows/test-integrations-*.yml` are the resulting workflow configuration YAMLs
14-
15-
If you update any of the components without keeping the rest in sync, for instance by making a change in one of the `test-integrations-*.yml` files that is not reflected in the templates in `scripts/split-tox-gh-actions/templates`, CI will error out as it actually checks if everything is in sync, meaning it runs the `split-tox-gh-actions.py` script and compares the result with the committed YAMLs.
9+
Since the number of integrations to test is so large, the tests in CI are split into multiple groups (roughly by integration type) so that they can run in parallel. So there is, for example, [a GitHub workflow](https://github.com/getsentry/sentry-python/blob/master/.github/workflows/test-integrations-flags.yml) that runs all our feature flag integrations, and [another one](https://github.com/getsentry/sentry-python/blob/master/.github/workflows/test-integrations-graphql.yml) that runs the test suites of all GraphQL integrations, and so on. These workflow YAMLs are auto-generated by [this script](https://github.com/getsentry/sentry-python/blob/master/scripts/split-tox-gh-actions/split-tox-gh-actions.py).
1610

17-
## AWS Lambda Test Suite
11+
The ultimate source of truth of what should be tested and on which versions (both Python versions as well as package versions) is stored in [`tox.ini`](https://github.com/getsentry/sentry-python/blob/master/tox.ini). This file is also auto-generated each week by a GitHub cron job that scans PyPI for new releases and updates the test matrix with them. The script that does this lives in [`scripts/populate_tox`](https://github.com/getsentry/sentry-python/tree/master/scripts/populate_tox) and is often referred to as "toxgen".
1812

19-
The AWS Lambda test suite will fail by default on new PRs. If you are an external contributor, this is not something you have to worry about, unless you've made changes actually affecting the AWS Lambda integration. It's a security precaution on our part.
13+
## The Big Picture
2014

21-
Sensitive test suites (currently only AWS Lambda) require maintainer review to ensure that tests do not compromise our secrets. This review must be repeated after any code revisions.
15+
There are multiple components to the test setup that runs in CI:
16+
* on a weekly basis, [`scripts/populate_tox`](https://github.com/getsentry/sentry-python/tree/master/scripts/populate_tox) creates a PR that updates `tox.ini` with new releases
17+
* `tox.ini` is where the configuration (what to test and what versions) is stored and read from
18+
* `scripts/split-tox-gh-actions/split-tox-gh-actions.py` is the script that defines the [test groups](https://github.com/getsentry/sentry-python/blob/0f3e5db0c8aabcad0baf0e8b2d3e31e27e839b3e/scripts/split-tox-gh-actions/split-tox-gh-actions.py#L57) and generates the resulting YAML files
19+
* `scripts/split-tox-gh-actions/templates` contains the jinja2 template snippets used to generate the YAML files
20+
* `.github/workflows/test-integrations-*.yml` are the resulting workflow configuration YAMLs
2221

23-
Before running sensitive test suites, maintainers need to carefully check the PR. Then they will apply the `Trigger: tests using secrets` label. The label will be removed after any code changes to enforce our policy requiring maintainers to review all code revisions before running sensitive tests.
22+
If you update any of the components without keeping the rest in sync, for instance by making a change in one of the `test-integrations-*.yml` files that is not reflected in the templates in `scripts/split-tox-gh-actions/templates`, they will be overwritten next time they're auto-generated.

‎develop-docs/sdk/processes/basics.mdx‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@ description: So you want to develop an SDK? Before you get started here are som
44
sidebar_order: 1
55
---
66

7+
<Alert>
8+
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.
9+
</Alert>
10+
711
## Run a Local Relay
812

913
You do not need a local Sentry for SDK development but you will want to run a local
@@ -39,9 +43,18 @@ a good idea to refer to already existing Sentry SDKs for input. In particular t
3943
transport design is not part of the documentation but generally quite similar between
4044
SDKs.
4145

42-
## Type out context in Relay
46+
## Define Conventions and Types Before Shipping
47+
48+
Before shipping new or changed SDK behavior, make sure the relevant definitions exist outside your SDK first:
49+
50+
- **Semantic conventions:** New or changed attributes **MUST** first be defined in [sentry-conventions](https://github.com/getsentry/sentry-conventions/). If the convention you need doesn't exist yet, open a PR there to propose it. Only after the convention has been merged should you implement it in an SDK. This ensures all SDKs use consistent naming and semantics.
51+
52+
The merge process for sentry-conventions PRs:
53+
1. Open a PR with the proposed convention.
54+
2. Get an approval from at least one code owner.
55+
3. Wait at least 3 business days after the first approval to give other code owners a chance to review.
4356

44-
To have a better understanding of various [context](https://develop.sentry.dev/sdk/data-model/event-payloads/contexts/) our SDKs emit, any newly added context should also be typed out in [Relay](https://github.com/getsentry/relay/tree/master/relay-event-schema/src/protocol/contexts).
57+
- **Context types:** Any newly added [context](https://develop.sentry.dev/sdk/data-model/event-payloads/contexts/) **SHOULD** also be typed out in [Relay](https://github.com/getsentry/relay/tree/master/relay-event-schema/src/protocol/contexts) so that the schema stays in sync with what SDKs emit.
4558

4659
## Join us on Discord
4760

‎develop-docs/sdk/processes/releases.mdx‎

Lines changed: 47 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,9 @@ Nice!
8585
This file is used to trigger the release from the GitHub UI.
8686

8787
You'll notice it uses `vars.SENTRY_RELEASE_BOT_CLIENT_ID` and `secrets.SENTRY_RELEASE_BOT_PRIVATE_KEY` -- these should be
88-
available to your repository automatically!
88+
available to your repository automatically! These are needed because
89+
[GitHub prevents `GITHUB_TOKEN` from triggering downstream workflows](https://docs.github.com/en/actions/reference/events-that-trigger-workflows),
90+
which is required for creating publish request issues in `getsentry/publish`.
8991

9092
```yaml
9193
name: Release
@@ -95,7 +97,7 @@ on:
9597
inputs:
9698
version:
9799
description: Version to release
98-
required: true
100+
required: false
99101
force:
100102
description: Force a release even when there are release-blockers (optional)
101103
required: false
@@ -111,28 +113,29 @@ jobs:
111113
with:
112114
app-id: ${{ vars.SENTRY_RELEASE_BOT_CLIENT_ID }}
113115
private-key: ${{ secrets.SENTRY_RELEASE_BOT_PRIVATE_KEY }}
114-
- uses: actions/checkout@v3
116+
- uses: actions/checkout@v6
115117
with:
116118
token: ${{ steps.token.outputs.token }}
117119
fetch-depth: 0
118120
- name: Prepare release
119-
uses: getsentry/action-prepare-release@v1
121+
uses: getsentry/craft@v2
120122
env:
121123
GITHUB_TOKEN: ${{ steps.token.outputs.token }}
122124
with:
123125
version: ${{ github.event.inputs.version }}
124126
force: ${{ github.event.inputs.force }}
125127
```
126128

129+
For full details on all available options including auto-versioning, changelog preview,
130+
and more, see [Craft's GitHub Actions documentation](https://craft.sentry.dev/github-actions/).
131+
If your repository is outside the `getsentry` organization, you can use the simpler
132+
[reusable workflow](https://craft.sentry.dev/github-actions/#option-1-reusable-workflow-recommended)
133+
which handles token management automatically via `secrets: inherit`.
134+
127135
### Commit + PR
128136

129137
**Commit those three files and make a pull request.**
130138

131-
Here's [an example PR] and the [follow-up to fix `fetch-depth`].
132-
133-
[an example PR]: https://github.com/getsentry/uwsgi-dogstatsd-plugin/pull/2
134-
[follow-up to fix `fetch-depth`]: https://github.com/getsentry/uwsgi-dogstatsd-plugin/pull/3
135-
136139
## Setting Up Permissions
137140

138141
Give the following teams access to your repository:
@@ -158,6 +161,37 @@ add a label to.
158161

159162
[issue in `publish`]: https://github.com/getsentry/publish/issues
160163

164+
## Calendar Versioning (CalVer)
165+
166+
To enable calendar versioning for your SDK, add the following to your `.craft.yml`:
167+
168+
```yaml
169+
versioning:
170+
policy: calver
171+
calver:
172+
format: "%y.%-m" # e.g., 24.12 for December 2024
173+
offset: 14 # Days to look back for date calculation (optional)
174+
```
175+
176+
See the [Craft CalVer documentation](https://craft.sentry.dev/configuration/#calendar-versioning-calver) for more details.
177+
178+
## Merge Target
179+
180+
By default, all releases are merged to the default branch of your repository (usually `main`). To override this, pass the `merge_target` input in your release workflow:
181+
182+
```yaml
183+
- name: Prepare release
184+
uses: getsentry/craft@v2
185+
env:
186+
GITHUB_TOKEN: ${{ steps.token.outputs.token }}
187+
with:
188+
version: ${{ github.event.inputs.version }}
189+
merge_target: ${{ github.event.inputs.merge_target }}
190+
```
191+
192+
Make sure to also add a `merge_target` input to your workflow's `workflow_dispatch.inputs` block.
193+
The same input is available in the [reusable workflow](https://craft.sentry.dev/github-actions/#option-1-reusable-workflow-recommended) as well.
194+
161195
## Version name conventions
162196

163197
To keep versioning consistent across SDKs, we generally follow [semantic versioning (semver)](https://semver.org/), with language- or platform-specific conventions around semver (if applicable).
@@ -227,7 +261,7 @@ You can opt your repo into using the config from a specific merge target branch
227261

228262
### 1. Release Preparation:
229263

230-
Add `craft_config_from_merge_target: true` when calling `getsentry/action-prepare-release` in your repo's release workflow:
264+
Add `craft_config_from_merge_target: true` when calling `getsentry/craft` in your repo's release workflow:
231265

232266
```yml
233267
# ...
@@ -238,12 +272,14 @@ jobs:
238272
steps:
239273
# ...
240274
- name: Prepare release
241-
uses: getsentry/action-prepare-release@v1
275+
uses: getsentry/craft@v2
242276
with:
243277
# ...
244278
craft_config_from_merge_target: true
245279
```
246280

281+
This input is also available in the [reusable workflow](https://craft.sentry.dev/github-actions/#option-1-reusable-workflow-recommended).
282+
247283
### 2. Publish Configuration
248284

249285
Add the branch(es) you want to take the config from to the `publish.yml` workflow in `getsentry/publish`:

0 commit comments

Comments
 (0)