diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 632f554df70a55..bc7683093e93ad 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -37,8 +37,8 @@ # ###### Replays ####### -# /docs/product/explore/session-replay/web @getsentry/replay-sdk-web @getsentry/replay-frontend @getsentry/replay-backend -# /docs/product/explore/session-replay/mobile @getsentry/replay-sdk-mobile @getsentry/replay-frontend @getsentry/replay-sdk-mobile +# /docs/product/explore/session-replay/web @getsentry/replay-sdk-web @getsentry/replay +# /docs/product/explore/session-replay/mobile @getsentry/replay-sdk-mobile @getsentry/replay @getsentry/replay-sdk-mobile # /includes/session-replay-web-report-bug.mdx @getsentry/replay-sdk-web # /platform-includes/session-replay/ @getsentry/replay-sdk-web @getsentry/replay-sdk-mobile # /docs/platforms/javascript/common/session-replay/ @getsentry/replay-sdk-web diff --git a/.github/labels.yml b/.github/labels.yml index a5e3ec38bc1804..5b60528a7270ff 100644 --- a/.github/labels.yml +++ b/.github/labels.yml @@ -284,6 +284,11 @@ color: 0E8A16 description: Prevents automatic closure of stale PRs +# AI evals - .github/workflows/ai-evals.yml +- name: 'ai-evals:llms_txt:sonnet-5.5:x3' + color: 6F42C1 + description: Run the llms.txt eval 3 times on Sonnet 5.5, on this PR's preview and its merge base's docs + # Miscellaneous - name: API Docs color: 649B42 @@ -304,6 +309,8 @@ color: '584774' - name: gatsby-bug color: e99695 +- name: Good First Issue + color: 4cb782 - name: "Hacktoberfest \U0001F383" color: ffa500 - name: Hacktoberfest-accepted @@ -316,6 +323,8 @@ - name: javascript color: F6F6F8 description: Pull requests that update Javascript code +- name: js-v11-docs + color: '206131' - name: Mobile color: f2c94c - name: performance diff --git a/.github/workflows/ai-evals.yml b/.github/workflows/ai-evals.yml new file mode 100644 index 00000000000000..de148332904008 --- /dev/null +++ b/.github/workflows/ai-evals.yml @@ -0,0 +1,257 @@ +# Runs the getsentry/sentry-for-ai-evals suites against this PR's docs. +# +# Label a PR `ai-evals:` to run the tests with that pytest mark on each target (a +# harness with a model) that repo's plan-evals action lists, or `ai-evals::` +# to run them on the targets whose `:` contains ``, and a last +# `:x` runs each test that many times, e.g. `ai-evals:llms_txt:sonnet-5.5:x3` for +# three runs on Sonnet 5.5 of the test that starts from llms.txt with no Sentry skills or +# MCP, only the docs. The labels are in .github/labels.yml, since sync-labels.yml deletes +# any label that isn't. Each label runs with two sets of docs and the same skills, from +# sentry-for-ai's `main`: the head reads docs.sentry.io from the PR's Vercel preview and +# the base from the production deploy of the PR's merge base. The plan job creates one run +# per label and side on evals.sentry.dev, and a job per test, target and side sends that +# test's result into it, each test in a clean container and all of them at once. A new +# push reruns every eval label still on the PR. +# +# A production deploy redirects every page to docs.sentry.io unless the request has the +# x-sentry-evals-pin header that the evals' docs proxy sends (middleware.ts). Deploys built +# before middleware.ts checked for it redirect anyway, so a merge base like that, or one +# with no production deploy, gets the live docs as the base, which is master as it is when +# the runs start. A head that's behind master is then missing what master gained since, and +# the comparison counts that as the PR's. The plan job warns then, and updating the branch, +# which reruns the evals, makes the comparison show only the PR. sentry-evals[bot] comments +# on the PR with the runs. +# +# sentry-for-ai-evals is internal, so the jobs check it out with the readonly bot's token +# and use its actions from that path. Fork PRs get no secrets, so they're skipped. This +# repo is public, so the eval outputs aren't kept as artifacts; the results go to +# evals.sentry.dev. + +name: AI Evals + +on: + pull_request: + types: [labeled, synchronize] + +permissions: {} + +jobs: + plan: + if: >- + github.event.pull_request.head.repo.full_name == github.repository && ( + (github.event.action == 'labeled' && startsWith(github.event.label.name, 'ai-evals:')) || + (github.event.action == 'synchronize' && contains(join(github.event.pull_request.labels.*.name, ','), 'ai-evals:')) + ) + runs-on: ubuntu-latest + # Mostly waiting for the preview, which is ready about 7 minutes after a push. + timeout-minutes: 30 + permissions: + contents: read + deployments: read + pull-requests: read + statuses: read + outputs: + evals-sha: ${{ steps.evals.outputs.commit }} + skills-sha: ${{ steps.skills.outputs.sha }} + docs-url: ${{ steps.preview.outputs.url }} + base-docs-url: ${{ steps.base.outputs.url }} + base-sha: ${{ steps.base.outputs.sha }} + eval-runs: ${{ steps.create.outputs.runs }} + eval-jobs: ${{ steps.create.outputs.jobs }} + steps: + - name: Get sentry-for-ai-evals token + id: token + uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0 + with: + client-id: ${{ vars.SENTRY_READONLY_BOT_CLIENT_ID }} + private-key: ${{ secrets.SENTRY_READONLYBOT_PRIVATE_KEY }} + repositories: sentry-for-ai-evals + permission-contents: read + + - id: evals + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + repository: getsentry/sentry-for-ai-evals + token: ${{ steps.token.outputs.token }} + path: sentry-for-ai-evals + persist-credentials: false + + - id: plan + uses: ./sentry-for-ai-evals/.github/actions/plan-evals + + # Both sides build the skills from the same commit, so only the docs differ. + - id: skills + run: | + ref="$(git ls-remote --exit-code https://github.com/getsentry/sentry-for-ai refs/heads/main)" + echo "sha=${ref%%$'\t'*}" >> "$GITHUB_OUTPUT" + + # vercel[bot] sets the commit status while the preview builds and creates the + # deployment, whose status has the URL, once it's done. This waits before the runs + # are created, since evals.sentry.dev fails a run that gets no result for 30 minutes. + - name: Wait for the Vercel preview + id: preview + if: steps.plan.outputs.count != '0' + env: + GH_TOKEN: ${{ github.token }} + PR_NUMBER: ${{ github.event.pull_request.number }} + HEAD_SHA: ${{ github.event.pull_request.head.sha }} + run: | + context="Vercel – sentry-docs" + environment="Preview – sentry-docs" + for (( i = 0; i < 40; i++ )); do + (( i == 0 )) || sleep 30 + # A newer push has a run of its own, so this one stops without creating runs. + current="$(gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER" --jq .head.sha)" || continue + if [[ "$current" != "$HEAD_SHA" ]]; then + echo "::notice::The PR's head is now $current, which its own run evaluates" + exit 0 + fi + statuses="$(gh api "repos/$GITHUB_REPOSITORY/commits/$HEAD_SHA/status")" || continue + IFS=$'\t' read -r state description < <(jq -r --arg c "$context" \ + '.statuses[] | select(.context == $c) | [.state, .description] | @tsv' <<<"$statuses") || true + case "$state" in + failure | error) + echo "::error::The sentry-docs preview of $HEAD_SHA failed: $description" + exit 1 + ;; + success) + ids="$(gh api -X GET "repos/$GITHUB_REPOSITORY/deployments" \ + -f sha="$HEAD_SHA" -f environment="$environment" --jq '.[].id')" || continue + url="" + for id in $ids; do + url="$(gh api "repos/$GITHUB_REPOSITORY/deployments/$id/statuses" \ + --jq 'map(select(.state == "success"))[0].environment_url // empty')" || continue + [[ -n "$url" ]] && break + done + if [[ -n "$url" ]]; then + # The agent reads the .md exports, without a bypass token. + if ! curl -fsS -o /dev/null "$url/index.md"; then + echo "::error::The preview at $url doesn't serve index.md, so the agent couldn't read docs from it" + exit 1 + fi + echo "Preview: $url" + echo "url=$url" >> "$GITHUB_OUTPUT" + exit 0 + fi + # A PR that only changes develop-docs doesn't build sentry-docs. + if [[ "$description" == *"Ignored Build Step"* ]]; then + echo "::error::Vercel didn't build a sentry-docs preview of $HEAD_SHA ($description). A PR that only changes develop-docs has no sentry-docs preview to evaluate." + exit 1 + fi + ;; + esac + done + echo "::error::No sentry-docs preview of $HEAD_SHA after 20 minutes" + exit 1 + + # The merge base's production deploy, if it serves its own pages to the pin header. + # curl doesn't follow redirects, so a deploy that redirects anyway isn't a 200. Else + # the live docs, right before the runs start so they're the ones the runs read, and + # behind_by counts the base branch's commits the head is missing. + - id: base + if: steps.preview.outputs.url != '' + env: + GH_TOKEN: ${{ github.token }} + # The branch, not base.sha, which is a snapshot from the event and can lag it. + BASE_REF: ${{ github.event.pull_request.base.ref }} + HEAD_SHA: ${{ github.event.pull_request.head.sha }} + run: | + compare="$(gh api "repos/$GITHUB_REPOSITORY/compare/$BASE_REF...$HEAD_SHA?per_page=1" \ + --jq '"\(.merge_base_commit.sha) \(.base_commit.sha) \(.behind_by)"')" + read -r merge_base base_tip behind <<<"$compare" + ids="$(gh api -X GET "repos/$GITHUB_REPOSITORY/deployments" \ + -f sha="$merge_base" -f environment="Production – sentry-docs" --jq '.[].id')" || ids="" + url="" + for id in $ids; do + url="$(gh api "repos/$GITHUB_REPOSITORY/deployments/$id/statuses" \ + --jq 'map(select(.state == "success"))[0].environment_url // empty')" || continue + [[ -n "$url" ]] && break + done + if [[ -n "$url" ]] && [[ "$(curl -sS -o /dev/null -w '%{http_code}' \ + -H 'x-sentry-evals-pin: 1' "$url/index.md")" == 200 ]]; then + echo "Base: $url, the production deploy of the merge base $merge_base" + echo "sha=$merge_base" >> "$GITHUB_OUTPUT" + echo "url=$url" >> "$GITHUB_OUTPUT" + exit 0 + fi + echo "sha=$base_tip" >> "$GITHUB_OUTPUT" + if (( behind > 0 )); then + echo "::warning::The merge base $merge_base has no production deploy that serves its own pages, so the base reads the live docs. The head is missing $behind of the base branch's commits, so the preview lacks changes the live docs have, and the comparison counts their removal as part of this PR. Update the branch to compare only this PR's changes, which reruns the evals." + fi + + # Each run records this repo's commits, the head and the base's (the merge base or the + # base branch's tip), and evals.sentry.dev pairs base and head runs by repository, so + # they never pair with sentry-for-ai's. + - id: create + if: steps.preview.outputs.url != '' + uses: ./sentry-for-ai-evals/.github/actions/create-runs + with: + runs: ${{ steps.plan.outputs.runs }} + skills-sha: ${{ steps.skills.outputs.sha }} + base-sha: ${{ steps.base.outputs.sha }} + evals-api-key: ${{ secrets.SENTRY_EVALS_API_KEY }} + + eval: + needs: plan + if: needs.plan.outputs.docs-url != '' && needs.plan.outputs.eval-jobs != '[]' + # By the test's number, not its name: sentry-for-ai-evals is internal, so this public + # repo's checks and logs don't name its tests. evals.sentry.dev has each test's result. + name: ${{ matrix.job.label }} (${{ matrix.job.revision }}, ${{ matrix.job.target.name }}, test ${{ matrix.job.test-index }}) + # Per PR, label, revision, target and test, so the jobs don't cancel each other. + concurrency: + group: ai-evals-${{ github.event.pull_request.number }}-${{ matrix.job.label }}-${{ matrix.job.revision }}-${{ matrix.job.target.name }}-${{ matrix.job.test-index }} + cancel-in-progress: true + runs-on: ubuntu-latest + timeout-minutes: 60 + permissions: + contents: read + strategy: + fail-fast: false + matrix: + # Each test a label selects, on each target the label picked, at each side. + job: ${{ fromJSON(needs.plan.outputs.eval-jobs) }} + steps: + - name: Get sentry-for-ai-evals token + id: token + uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0 + with: + client-id: ${{ vars.SENTRY_READONLY_BOT_CLIENT_ID }} + private-key: ${{ secrets.SENTRY_READONLYBOT_PRIVATE_KEY }} + repositories: sentry-for-ai-evals + permission-contents: read + + # Side by side, so the evals don't copy sentry-for-ai into their image. + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + repository: getsentry/sentry-for-ai-evals + ref: ${{ needs.plan.outputs.evals-sha }} + token: ${{ steps.token.outputs.token }} + path: sentry-for-ai-evals + persist-credentials: false + + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + repository: getsentry/sentry-for-ai + ref: ${{ needs.plan.outputs.skills-sha }} + path: sentry-for-ai + persist-credentials: false + + # Sends this test's result into the run the plan job created for the label and + # side. The head reads the preview, and the base the merge base's production deploy + # when the plan job found one, or else the live docs. No artifact-name: this repo is + # public. + - uses: ./sentry-for-ai-evals/.github/actions/run-evals + with: + marker: ${{ matrix.job.marker }} + test-index: ${{ matrix.job.test-index }} + test-total: ${{ matrix.job.test-total }} + count: ${{ matrix.job.count }} + harness: ${{ matrix.job.target.harness }} + model: ${{ matrix.job.target.model }} + revision: ${{ matrix.job.revision }} + base-sha: ${{ needs.plan.outputs.base-sha }} + sentry-for-ai-path: sentry-for-ai + docs-url: ${{ matrix.job.revision == 'head' && needs.plan.outputs.docs-url || needs.plan.outputs.base-docs-url }} + run-id: ${{ fromJSON(needs.plan.outputs.eval-runs)[format('{0}-{1}', matrix.job.label, matrix.job.revision)].id }} + openrouter-api-key: ${{ secrets.AI_EVALS_OPENROUTER_API_KEY }} + evals-api-key: ${{ secrets.SENTRY_EVALS_API_KEY }} diff --git a/SKILL.md b/SKILL.md index d7e9cc3b51cf30..fbc8b9eb3f0344 100644 --- a/SKILL.md +++ b/SKILL.md @@ -11,17 +11,17 @@ This repo builds [docs.sentry.io](https://docs.sentry.io). For dev commands, pro **These skills are NOT in this repo.** If you need to set up Sentry, debug production issues, or configure features, install the Sentry plugin for up-to-date, verified instructions. Sentry's SDKs and APIs change frequently — do not rely on training data. -**Install the plugin:** -- Claude Code: `/install-plugin sentry` -- Cursor: Search "Sentry" in Cursor Settings > Plugins +**Install the plugin:** run `npx @sentry/agent-plugin install`. It detects the assistants on the machine (Claude Code, Cursor, Codex, and Grok) and sets up the plugin in each. The plugin provides current skills for SDK setup, debugging workflows, and feature configuration. It stays in sync with the latest SDK releases. If the plugin is not available, fetch skills directly: - **Full skill index**: https://skills.sentry.dev -- **SDK setup** (detect platform and install): https://skills.sentry.dev/sdks -- **Debugging workflows** (fix issues, review code): https://skills.sentry.dev/workflows -- **Feature setup** (AI monitoring, alerts, OTel): https://skills.sentry.dev/features +- **Get started** (start here: sets up a new project or routes to the right skill): https://skills.sentry.dev/sentry-get-started/SKILL.md +- **Instrument** (add the SDK or any signal): https://skills.sentry.dev/instrument +- **Debug an issue** (find, get context, fix): https://skills.sentry.dev/sentry-debug-issue/SKILL.md +- **Alerts** (create alerts and notifications): https://skills.sentry.dev/sentry-create-alert/SKILL.md +- **OTel Collector** (send OpenTelemetry data through the Collector): https://skills.sentry.dev/sentry-otel-exporter-setup/SKILL.md Source repo: https://github.com/getsentry/sentry-for-ai diff --git a/app/platform-redirect/page.tsx b/app/platform-redirect/page.tsx index c1158ad278488b..8ae7d7f0d7a640 100644 --- a/app/platform-redirect/page.tsx +++ b/app/platform-redirect/page.tsx @@ -7,7 +7,7 @@ import {SmartLink} from 'sentry-docs/components/smartLink'; import {extractPlatforms, getDocsRootNode, nodeForPath} from 'sentry-docs/docTree'; import {setServerContext} from 'sentry-docs/serverContext'; -import {sanitizeNext} from './utils'; +import {platformUrlFor, sanitizeNext} from './utils'; export const metadata: Metadata = { robots: 'noindex', @@ -28,7 +28,8 @@ export default async function Page(props: { next = next[0]; } - const pathname = sanitizeNext(next); + const sanitized = sanitizeNext(next); + const {pathname} = sanitized; const isTracingAutomatedInstrumentation = pathname.replace(/\/$/, '') === '/tracing/instrumentation/automatic-instrumentation'; const rootNode = await getDocsRootNode(); @@ -145,7 +146,7 @@ export default async function Page(props: { p => p.key === requestedPlatform?.toLowerCase() ); if (validPlatform) { - return redirect(`${validPlatform.url}${pathname}`); + return redirect(platformUrlFor(validPlatform.url, sanitized)); } } @@ -167,7 +168,7 @@ export default async function Page(props: {
    {platformOrGuideList.map(p => (
  • - + sanitizeNext(next).pathname; +const hash = (next: string) => sanitizeNext(next).hash; +const REJECTED = {pathname: '', hash: ''}; describe('sanitizeNext', () => { it('should return an empty string for external URLs', () => { - expect(sanitizeNext('http://example.com')).toBe(''); - expect(sanitizeNext('https://example.com')).toBe(''); - expect(sanitizeNext('//example.com')).toBe(''); + expect(sanitizeNext('http://example.com')).toEqual(REJECTED); + expect(sanitizeNext('https://example.com')).toEqual(REJECTED); + expect(sanitizeNext('//example.com')).toEqual(REJECTED); }); it('should reject backslash-based external URLs', () => { // Browsers normalize backslashes to forward slashes, so these would // otherwise resolve to an external origin. - expect(sanitizeNext('/\\example.com')).toBe(''); - expect(sanitizeNext('/\\/example.com')).toBe(''); - expect(sanitizeNext('\\\\example.com')).toBe(''); - expect(sanitizeNext('\\/example.com')).toBe(''); - expect(sanitizeNext('%2F%5Cexample.com')).toBe(''); - expect(sanitizeNext('///example.com')).toBe(''); + expect(sanitizeNext('/\\example.com')).toEqual(REJECTED); + expect(sanitizeNext('/\\/example.com')).toEqual(REJECTED); + expect(sanitizeNext('\\\\example.com')).toEqual(REJECTED); + expect(sanitizeNext('\\/example.com')).toEqual(REJECTED); + expect(sanitizeNext('%2F%5Cexample.com')).toEqual(REJECTED); + expect(sanitizeNext('///example.com')).toEqual(REJECTED); }); it('should reject control characters that resolve to an external origin', () => { // The URL parser strips tabs and newlines, so `//host` becomes `//host` - expect(sanitizeNext('/%09/example.com')).toBe(''); - expect(sanitizeNext('/%0a/example.com')).toBe(''); - expect(sanitizeNext('/%0d/example.com')).toBe(''); + expect(sanitizeNext('/%09/example.com')).toEqual(REJECTED); + expect(sanitizeNext('/%0a/example.com')).toEqual(REJECTED); + expect(sanitizeNext('/%0d/example.com')).toEqual(REJECTED); }); it('should never return a protocol-relative path', () => { // Stripping unsafe characters must not leave adjacent slashes behind - expect(sanitizeNext('/,/example.com')).toBe('/examplecom'); - expect(sanitizeNext('/a//b')).toBe('/a/b'); + expect(path('/,/example.com')).toBe('/examplecom'); + expect(path('/a//b')).toBe('/a/b'); }); it('should reject non-http schemes', () => { // eslint-disable-next-line no-script-url -- asserting this is rejected - expect(sanitizeNext('javascript:alert(1)')).toBe(''); - expect(sanitizeNext('data:text/html,x')).toBe(''); + expect(sanitizeNext('javascript:alert(1)')).toEqual(REJECTED); + expect(sanitizeNext('data:text/html,x')).toEqual(REJECTED); }); it('should resolve dot segments', () => { - expect(sanitizeNext('/a/./b')).toBe('/a/b'); - expect(sanitizeNext('/a/../../b')).toBe('/b'); + expect(path('/a/./b')).toBe('/a/b'); + expect(path('/a/../../b')).toBe('/b'); }); it('should normalize backslashes within a path', () => { - expect(sanitizeNext('/path\\to/resource')).toBe('/path/to/resource'); + expect(path('/path\\to/resource')).toBe('/path/to/resource'); }); it('should prepend a slash if missing', () => { - expect(sanitizeNext('path/to/resource')).toBe('/path/to/resource'); + expect(path('path/to/resource')).toBe('/path/to/resource'); }); it('should not modify a valid internal path', () => { - expect(sanitizeNext('/path/to/resource')).toBe('/path/to/resource'); + expect(path('/path/to/resource')).toBe('/path/to/resource'); }); it('should remove unsafe characters', () => { - expect(sanitizeNext('/path/to/resource?query=1')).toBe('/path/to/resource'); - expect(sanitizeNext('/path/to/resource#hash')).toBe('/path/to/resource'); + expect(path('/path/to/resource?query=1')).toBe('/path/to/resource'); }); it('should allow alphanumeric and hyphens', () => { - expect(sanitizeNext('/path-to/resource123')).toBe('/path-to/resource123'); + expect(path('/path-to/resource123')).toBe('/path-to/resource123'); }); it('should return an empty string for paths with colons', () => { - expect(sanitizeNext('/path:to/resource')).toBe(''); + expect(sanitizeNext('/path:to/resource')).toEqual(REJECTED); }); it('should return an empty string for the root path', () => { - expect(sanitizeNext('/')).toBe(''); + expect(path('/')).toBe(''); }); it('should decode URL encoded characters', () => { - expect(sanitizeNext('/path%2Fwith%2Fslashes')).toBe('/path/with/slashes'); + expect(path('/path%2Fwith%2Fslashes')).toBe('/path/with/slashes'); }); it('should return an empty string for a malformed URI component', () => { - const input = '%E0%A4%A'; // Malformed URI - const expectedOutput = ''; - expect(sanitizeNext(input)).toBe(expectedOutput); + expect(sanitizeNext('%E0%A4%A')).toEqual(REJECTED); + }); + + describe('fragments', () => { + it('should keep the fragment alongside the path', () => { + expect(sanitizeNext('/configuration/options/#tracing-options')).toEqual({ + pathname: '/configuration/options/', + hash: '#tracing-options', + }); + }); + + it('should keep the fragment when it arrives percent-encoded', () => { + expect(sanitizeNext('%2Fconfiguration%2Foptions%2F%23ignoreErrors')).toEqual({ + pathname: '/configuration/options/', + hash: '#ignoreErrors', + }); + }); + + it('should allow dots in a fragment', () => { + // e.g. Godot's `godot_logger.event_mask` + expect(hash('/configuration/options/#godot_logger.event_mask')).toBe( + '#godot_logger.event_mask' + ); + }); + + it('should keep the fragment out of the path', () => { + expect(path('/configuration/options/#tracing-options')).toBe( + '/configuration/options/' + ); + }); + + it('should drop an unrecognized fragment but keep the path', () => { + expect(sanitizeNext('/configuration/options/#a b')).toEqual({ + pathname: '/configuration/options/', + hash: '', + }); + expect(sanitizeNext('/configuration/options/#')).toEqual({ + pathname: '/configuration/options/', + hash: '', + }); + }); + + it('should not let a fragment smuggle in an origin', () => { + expect(hash('/a/#@example.com')).toBe(''); + expect(hash('/a/#//example.com')).toBe(''); + }); + + it('should not treat a double-encoded fragment as one', () => { + // `%2523` decodes to `%23`, which is a path character, not a delimiter + expect(sanitizeNext('/a/%2523b')).toEqual({pathname: '/a/23b', hash: ''}); + }); + }); +}); + +describe('platformUrlFor', () => { + it('should not leave a double slash between the platform and the path', () => { + expect( + platformUrlFor('/platforms/python/', { + pathname: '/configuration/options/', + hash: '', + }) + ).toBe('/platforms/python/configuration/options/'); + }); + + it('should append the fragment', () => { + expect( + platformUrlFor('/platforms/python/', { + pathname: '/configuration/options/', + hash: '#tracing-options', + }) + ).toBe('/platforms/python/configuration/options/#tracing-options'); + }); + + it('should keep the platform URL intact when there is no path', () => { + expect(platformUrlFor('/platforms/python/', {pathname: '', hash: ''})).toBe( + '/platforms/python/' + ); + expect(platformUrlFor('/platforms/python/', {pathname: '', hash: '#x'})).toBe( + '/platforms/python/#x' + ); }); }); diff --git a/app/platform-redirect/utils.ts b/app/platform-redirect/utils.ts index 8148cf56956a17..e646c519afcaba 100644 --- a/app/platform-redirect/utils.ts +++ b/app/platform-redirect/utils.ts @@ -1,17 +1,30 @@ // Parse base only — never part of the return value, and only compared against itself const PARSE_BASE = 'https://sanitize.invalid'; -export const sanitizeNext = (next: string) => { +// Heading slugs in the docs are word characters, hyphens and dots +// (for example `godot_logger.event_mask`) +const SAFE_HASH = /^#[\w.-]+$/; + +export type SanitizedNext = { + /** Empty, or a `#`-prefixed fragment safe to append to a resolved URL */ + hash: string; + /** Empty, or an absolute docs path with no origin, query or fragment */ + pathname: string; +}; + +const EMPTY: SanitizedNext = {pathname: '', hash: ''}; + +export const sanitizeNext = (next: string): SanitizedNext => { let decoded: string; try { decoded = decodeURIComponent(next); } catch { - return ''; + return EMPTY; } // No docs path contains a colon; also keeps `javascript:`/`data:` out of the parser if (decoded.includes(':')) { - return ''; + return EMPTY; } let url: URL; @@ -21,11 +34,11 @@ export const sanitizeNext = (next: string) => { // our origin shows up as a foreign `origin` rather than as a path to untangle url = new URL(decoded, PARSE_BASE); } catch { - return ''; + return EMPTY; } if (url.origin !== PARSE_BASE) { - return ''; + return EMPTY; } const pathname = url.pathname @@ -33,5 +46,22 @@ export const sanitizeNext = (next: string) => { // stripping can leave `//`, which would resolve as protocol-relative .replace(/\/{2,}/g, '/'); - return pathname === '/' ? '' : pathname; + // The fragment is kept apart from the path: callers resolve the path against the + // doc tree and only append the fragment to the URL they build from it. A fragment + // we don't recognize is dropped rather than failing the whole redirect. + const hash = SAFE_HASH.test(url.hash) ? url.hash : ''; + + return {pathname: pathname === '/' ? '' : pathname, hash}; +}; + +/** + * Joins a platform URL (which always ends in `/`) with a sanitized path and fragment + * without leaving the `//` that would cost an extra redirect hop. + */ +export const platformUrlFor = ( + platformUrl: string, + {pathname, hash}: SanitizedNext +): string => { + const base = pathname ? `${platformUrl.replace(/\/+$/, '')}${pathname}` : platformUrl; + return `${base}${hash}`; }; diff --git a/develop-docs/application-architecture/dynamic-sampling/the-big-picture.mdx b/develop-docs/application-architecture/dynamic-sampling/the-big-picture.mdx index a2083ffc965a0b..fc2e85afa733be 100644 --- a/develop-docs/application-architecture/dynamic-sampling/the-big-picture.mdx +++ b/develop-docs/application-architecture/dynamic-sampling/the-big-picture.mdx @@ -92,7 +92,7 @@ For more granular queries, **stored events are needed**. _The purpose of dynamic If Sentry applies a 1% dynamic sample rate, you can still receive accurate events per minute (SPM or TPM, depending on event type) and web vital quantiles through total event data backed by metrics. There is also a listing of each of these numbers by the transaction. -When you go into Trace Explorer or Errors, you might want to now split the data by a custom tag you’ve added to your events. This granularity is not offered by metrics, so **these queries need to use stored events**. +When you go into Explore → Traces or Errors, you might want to now split the data by a custom tag you’ve added to your events. This granularity is not offered by metrics, so **these queries need to use stored events**. diff --git a/develop-docs/sdk/foundations/trace-propagation/dynamic-sampling-context.mdx b/develop-docs/sdk/foundations/trace-propagation/dynamic-sampling-context.mdx index b77d5ce1e7bcb7..3aeed6dbae348d 100644 --- a/develop-docs/sdk/foundations/trace-propagation/dynamic-sampling-context.mdx +++ b/develop-docs/sdk/foundations/trace-propagation/dynamic-sampling-context.mdx @@ -2,7 +2,7 @@ title: Dynamic Sampling Context (DSC) description: How SDKs propagate Dynamic Sampling Context via baggage headers and envelope headers. spec_id: sdk/foundations/trace-propagation/dynamic-sampling-context -spec_version: 1.3.0 +spec_version: 1.4.0 spec_status: stable spec_depends_on: - id: sdk/foundations/trace-propagation @@ -10,6 +10,9 @@ spec_depends_on: - id: sdk/foundations/transport/envelopes version: ">=1.0.0" spec_changelog: + - version: 1.4.0 + date: 2026-10-19 + summary: Don't freeze an empty DSC when continuing a trace without baggage; create it from the segment span instead (required for span streaming) - version: 1.3.0 date: 2026-02-24 summary: Moved to trace-propagation sub-spec @@ -203,6 +206,7 @@ DSC leaves SDKs in two situations: When an SDK receives an HTTP request that was "instrumented" or "traced" by a Sentry SDK, the receiving SDK **MUST** consider the incoming DSC as instantly frozen. Any values on the DSC **MUST** be propagated "as is" — this includes values like "environment" or "release". +If the incoming request has a `sentry-trace` header but no DSC (no `baggage` header with `sentry-` values), see [Incoming Trace Without DSC](#incoming-trace-without-dsc). SDKs **SHOULD** recognize incoming requests as "instrumented" or "traced" when at least one of the following applies: @@ -217,7 +221,52 @@ After the DSC of a particular trace has been frozen, API calls like `set_user` * ### Unified Propagation Mechanism -SDKs **SHOULD** follow these steps for any incoming and outgoing requests (in python pseudo-code for illustrative purposes): +SDKs **SHOULD** follow these steps for any incoming and outgoing requests (in python pseudo-code for illustrative purposes). For transaction-based SDKs, the segment span is the transaction: + +```python +def collect_dynamic_sampling_context(): + # Placeholder function that collects as many values for Dynamic Sampling Context + # as possible and returns a dict + +def has_sentry_value_in_baggage_header(request): + # Placeholder function that returns True when there is at least one key-value pair in the baggage + # header of `request`, for which the key starts with "sentry-". Otherwise, it returns False. + +def on_incoming_request(request): + # Only applies if the SDK continues the incoming trace (see strict trace continuation) + if request.has_header("sentry-trace") and (not request.has_header("baggage") or not has_sentry_value_in_baggage_header(request)): + # Request comes from an old SDK which doesn't support Dynamic Sampling Context yet + # --> we don't freeze the DSC. Instead, it is created from our own segment span + # as late as possible (on the first outgoing request or when the envelope is sent) + current_segment_span.dynamic_sampling_context_frozen = False + elif request.has_header("sentry-trace") and request.has_header("baggage") and has_sentry_value_in_baggage_header(request): + current_segment_span.dynamic_sampling_context_frozen = True + current_segment_span.dynamic_sampling_context = baggage_header_to_dict(request.headers.baggage) + +def on_outgoing_request(request): + if not current_segment_span.dynamic_sampling_context_frozen: + current_segment_span.dynamic_sampling_context_frozen = True + current_segment_span.dynamic_sampling_context = merge_dicts(collect_dynamic_sampling_context(), current_segment_span.dynamic_sampling_context) + + if request.has_header("baggage"): + outgoing_baggage_dict = baggage_header_to_dict(request.headers.baggage) + merged_baggage_dict = merge_dicts(outgoing_baggage_dict, current_segment_span.dynamic_sampling_context) + request.set_header("baggage", dict_to_baggage_header(merged_baggage_dict)) + else: + request.set_header("baggage", dict_to_baggage_header(current_segment_span.dynamic_sampling_context)) + +def on_envelope_send(envelope): + if not current_segment_span.dynamic_sampling_context_frozen: + current_segment_span.dynamic_sampling_context_frozen = True + current_segment_span.dynamic_sampling_context = merge_dicts(collect_dynamic_sampling_context(), current_segment_span.dynamic_sampling_context) + + envelope.headers.trace = current_segment_span.dynamic_sampling_context +``` + + + +Before spec version `1.4.0`, SDKs froze an empty DSC when the incoming request had a `sentry-trace` header but no DSC. +SDKs that don't implement [span streaming](/sdk/telemetry/spans/) **MAY** keep following this behavior: ```python def collect_dynamic_sampling_context(): @@ -255,11 +304,30 @@ def on_outgoing_request(request): request.set_header("baggage", dict_to_baggage_header(current_transaction.dynamic_sampling_context)) ``` -While there is no strict necessity for the `current_transaction.dynamic_sampling_context_frozen` flag yet, there is a future use case where we need it: + + +While there is no strict necessity for the `dynamic_sampling_context_frozen` flag yet, there is a future use case where we need it: We might want users to be able to set Dynamic Sampling Context values themselves. The flag becomes relevant after the first propagation, where Dynamic Sampling Context becomes immutable. When users attempt to set DSC afterwards, our SDKs **SHOULD** make this operation a noop. +#### Incoming Trace Without DSC + +If an SDK receives a `sentry-trace` header but no DSC (no `baggage` header with `sentry-` values), continues the trace, and starts a segment span: + +- The SDK **MUST** create the DSC from its own segment span, collecting as many [DSC values](#dsc-specification) as possible. `trace_id` **MUST** match the continued trace, and `sampled` **MUST** match the segment span's sampling decision. +- The new DSC's `sample_rate` **MUST** be set to: + - the returned sample rate if a `tracesSampler` callback was invoked. + - `1.0` for a positive and `0.0` for a negative sampling decision, if the sampling decision was inherited from the `sentry-trace` header. + - the local `tracesSampleRate` from the SDK's options, if the incoming `sentry-trace` header had no sampling decision ("deferred sampling"). + - omit `sample_rate` in the DSC, if there is no local `tracesSampleRate` or `tracesSampler`, in which case [deferred sampling DSC](../#deferred-sampling) is created. +- The SDK **SHOULD** materialize and freeze this DSC as late as possible, either on the first outgoing request or when the first envelope is sent. For span streaming, see [Serialization and Dynamic Sampling Context](/sdk/telemetry/spans/#serialization-and-dynamic-sampling-context). + +SDKs implementing [span streaming](/sdk/telemetry/spans/) **MUST** follow this behavior, because span envelopes require a `trace` envelope header. Other SDKs **SHOULD** follow it, but **MAY** keep the previous behavior from versions 1.0.0 to 1.3.0. + +A common reason for this scenario is old SDKs not compatible with DSC starting traces. Therefore, they +only send the `sentry-trace` but no `baggage` header with `sentry-` values. + --- diff --git a/develop-docs/sdk/telemetry/spans/index.mdx b/develop-docs/sdk/telemetry/spans/index.mdx index 14ede26809eaee..93ecb3d684592b 100644 --- a/develop-docs/sdk/telemetry/spans/index.mdx +++ b/develop-docs/sdk/telemetry/spans/index.mdx @@ -2,14 +2,19 @@ title: Spans description: Span creation, sampling, filtering, buffering, and wire format for the span-first tracing model. spec_id: sdk/telemetry/spans -spec_version: 1.1.0 +spec_version: 1.2.0 spec_status: stable spec_depends_on: - id: sdk/foundations/transport/envelopes version: ">=1.0.0" - id: sdk/foundations/trace-propagation version: ">=1.0.0" + - id: sdk/foundations/trace-propagation/dynamic-sampling-context + version: ">=1.4.0" spec_changelog: + - version: 1.2.0 + date: 2026-10-19 + summary: Require DSC spec 1.4.0 so span envelopes always have a trace envelope header, even for incoming traces without baggage - version: 1.1.0 date: 2026-10-08 summary: Added client reports section listing discard reasons for spans and clarifying that the quantity is the number of discarded spans @@ -614,6 +619,8 @@ The envelope header **MUST** contain the same properties as previously with tran Unlike transactions, envelope headers for spans **REQUIRE** [Dynamic Sampling Context](/sdk/foundations/trace-propagation/dynamic-sampling-context/). See also [Envelope Headers](/sdk/foundations/envelopes/#headers). +To guarantee a DSC for every span envelope, SDKs implementing span streaming **MUST** follow version 1.4.0 or later of the DSC spec. + ### Span v2 Envelope Item Header | Property | Type | Required | Description | diff --git a/develop-docs/sdk/telemetry/traces/index.mdx b/develop-docs/sdk/telemetry/traces/index.mdx index 442192074fb1ba..deeb0e8966f622 100644 --- a/develop-docs/sdk/telemetry/traces/index.mdx +++ b/develop-docs/sdk/telemetry/traces/index.mdx @@ -161,7 +161,7 @@ In memory, spans build up a conceptual tree of timed operations. We call the who Over the wire, transactions are serialized to JSON as an augmented `Event`, and sent as envelopes. The different envelope types are for optimizing ingestion (so we can route "transaction events" differently than other events, mostly "error events"). -In the Sentry UI, you can use Errors and Trace Explorer to look at error and performance events, and the Issues section to dive into grouped errors. The [user-facing tracing documentation](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/) explains more of the concepts on the product level. +In the Sentry UI, you can use Errors and Explore → Traces to look at error and performance events, and the Issues section to dive into grouped errors. The [user-facing tracing documentation](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/) explains more of the concepts on the product level. The [Span](/sdk/foundations/transport/event-payloads/span/) class stores each individual span in a trace. diff --git a/develop-docs/sdk/telemetry/traces/span-links.mdx b/develop-docs/sdk/telemetry/traces/span-links.mdx index 5fca4c0d459bd5..02de4768affa8d 100644 --- a/develop-docs/sdk/telemetry/traces/span-links.mdx +++ b/develop-docs/sdk/telemetry/traces/span-links.mdx @@ -146,8 +146,8 @@ Any string can be used, but these types have predefined meanings: | `sentry.link.type` | Usage | UI Implications | |--------------------|--------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------| | "previous_trace" | Linking e.g. a navigation span to the previous page load span. | Used to query linked traces. Shows a button to go to linked previous trace in the trace explorer. | -| "next_trace" | Linking e.g. a page load span to the next navigation span. | Used to query linked traces. Shows a button to go to linked next trace in the trace explorer. | | "cache_origin" | Linking a span that reads a cached value to the trace that produced that value (e.g. server-side rendering). | Used to navigate from a cache-hit span to the origin trace. | +| "message_origin" | Linking a span that processes a queue message to the span that published the message (e.g. a queue job). | Used to navigate from a consumer span to the producer trace. | ### `previous_trace` @@ -210,6 +210,35 @@ The origin trace may be negatively sampled. The link is still added, with `sampl A background revalidation (for example, stale-while-revalidate) starts its own trace rather than continuing the serving trace, and becomes the origin for future cache hits. +### `message_origin` + +When a consumer processes a message, the work often runs long after the producer published it, in another process, and with a different sampling decision. +A parent/child relationship does not fit well: a delayed or retried job keeps the producer trace open for a long time, one publish span can fan out to many consumers, and a batch can contain messages from unrelated traces, so it has no single correct parent. +If the consumer starts its own trace, then without a link, the consumer trace has no way to find the code that published the message. + +The [Queues module](/sdk/telemetry/traces/modules/queues/#distributed-tracing) continues the producer trace in the consumer where it can. +For the cases above, start a new trace in the consumer and add a `message_origin` link instead. +If the consumer continues the producer trace, do not add the link, because it would point into the same trace. + +A `message_origin` link connects the span that processes a message (for example, a `queue.process` span) to the span that published it (for example, a `queue.publish` span). "Origin" here means the producer span, not the consumer. + +Add the link to the span that processes the message: + +```ts +span.addLink({ + context: producerSpanContext, // propagated with the message + attributes: { + 'sentry.link.type': 'message_origin' + } +}) +``` + +- On publish, store the context of the publish span (for example, the `queue.publish` span: `trace_id`, `span_id`, sampling decision) with the message, for example in message metadata or headers. +- On process, read the stored context and add the link. A span that processes a batch adds one link for each distinct producer span in the batch. +- If the message has no stored context, emit the consumer span **without** a link. + +The producer trace may be negatively sampled. The link is still added, with `sampled: false` from the stored span context (same behavior as `previous_trace`). + ## Usage Example Adding span links should be possible at span start time, as well as when holding a reference to the span. diff --git a/develop-docs/self-hosted/releases.mdx b/develop-docs/self-hosted/releases.mdx index d400d3dd72654f..f5720d28b4a30d 100644 --- a/develop-docs/self-hosted/releases.mdx +++ b/develop-docs/self-hosted/releases.mdx @@ -19,9 +19,9 @@ Sentry cuts regular releases for self-hosting to keep it as close to [sentry.io] ## Upgrading -We encourage everyone to regularly update their Sentry installations to get the best and the most recent Sentry experience. +We encourage everyone to regularly update their Sentry installations to get the best and the most recent Sentry experience. The best upgrade interval is every month, as this is the frequency of our release schedule. -Before starting the upgrade, we shut down all the services and then run some data migrations, so expect to have some downtime. There is an *experimental* `--minimize-downtime` option to reduce the downtime during upgrades. Use this at your own risk and see [the pull request it was implemented in](https://github.com/getsentry/self-hosted/issues/607) for more information. +Before starting the upgrade, we shut down all the services and then run some data migrations, so expect to have some downtime. There is an *experimental* `--minimize-downtime` option to reduce the downtime during upgrades. Use this at your own risk and see [the pull request it was implemented in](https://github.com/getsentry/self-hosted/issues/607) for more information. We assume you've cloned the self-hosted repository, so checkout the version you want to upgrade to (25.7.0 as an example). @@ -37,8 +37,6 @@ git checkout 25.7.0 We may have some updated configuration, especially for new features, so always check the example config files under the sentry directory and see if you need to update your existing configuration. We do our best to automate critical configuration updates, but you should always check your configs during upgrades. -If you have a `.env.custom` file, make sure to copy new environment variables from the `.env` file into the `.env.custom` file before running the install script. - Finally, to upgrade, run `./install.sh`. Upon completion, run `docker compose up --wait` (or if you have `.env.custom` file, run `docker compose --env-file .env --env-file .env.custom up --wait`). ### Hard Stops @@ -81,7 +79,7 @@ This section lists known issues with specific versions of the self-hosted Sentry ## Nightly Builds -We provide nightly builds from the [master branch of the self-hosted repository](https://github.com/getsentry/self-hosted/) for each new commit for [Sentry](https://github.com/getsentry/sentry), and all of the supporting projects: +We provide nightly builds from the [master branch of the self-hosted repository](https://github.com/getsentry/self-hosted/) for each new commit for [Sentry](https://github.com/getsentry/sentry), and all of the supporting projects: - [Snuba](https://github.com/getsentry/snuba) - [Relay](https://github.com/getsentry/relay) @@ -89,8 +87,9 @@ We provide nightly builds from the [master branch of the self-hosted repository - [Vroom](https://github.com/getsentry/vroom) - [Uptime Checker](https://github.com/getsentry/uptime-checker) - [Taskbroker](https://github.com/getsentry/taskbroker) +- [Launchpad](https://github.com/getsentry/launchpad) -These builds are usually stable, but you may occasionally hit a broken version as these versions are not guaranteed to be deployed to [sentry.io](http://sentry.io/) first. There is also no guarantee that you will be able to do a clean upgrade to later versions without losing any data. **Use the nightly builds at your own risk.** +These builds are usually stable, but you may occasionally hit a broken version as these versions are not guaranteed to be deployed to [sentry.io](http://sentry.io/) right away, or due to missing configuration. There is also no guarantee that you will be able to do a clean upgrade to later versions without losing any data. **Use the nightly builds at your own risk.** ## Breaking Changes diff --git a/docs/account/user-settings/index.mdx b/docs/account/user-settings/index.mdx index 56ef7a493dac3b..c55a7fe0df885b 100644 --- a/docs/account/user-settings/index.mdx +++ b/docs/account/user-settings/index.mdx @@ -47,4 +47,8 @@ The email address used to log into your Sentry account is, by default, your prim Warning: Deleting your account cannot be undone. -Closing your Sentry account automatically [removes all data](https://sentry.io/security/#data-removal) associated with your account after a 24-hour waiting period to prevent accidental cancellation. If your account is the sole owner of an organization, this organization will be deleted. Organizations with multiple owners will remain unchanged. For details about termination of service, see [Term, Termination, and Effect of Termination](https://sentry.io/terms/#term-termination-and-effect-of-termination). +Closing your Sentry account automatically [removes all data](https://sentry.io/security/#data-removal) associated with your account within 24 hours. The account will be fully deleted 30 days after your last login. + +You will receive an email notification when your account is officially pending deletion. Your account will remain in this state for 30 days, during which you can log back in to cancel the deletion. + +If your account is the sole owner of an organization, this organization will be deleted. Organizations with multiple owners will remain unchanged. For details about termination of service, see [Term, Termination, and Effect of Termination](https://sentry.io/terms/#term-termination-and-effect-of-termination). diff --git a/docs/cli/code-mappings.mdx b/docs/cli/code-mappings.mdx index be4f0e7000cc8b..5c65918fc8e813 100644 --- a/docs/cli/code-mappings.mdx +++ b/docs/cli/code-mappings.mdx @@ -10,7 +10,7 @@ _Available in version 3.3.4 of Sentry CLI_ Code mappings link stack trace paths to source code paths in your repository. They enable features like [source context](/platforms/java/source-context/), [suspect commits](/product/issues/suspect-commits/), [stack trace linking](/integrations/source-code-mgmt/github/#stack-trace-linking), and [code owners](/product/issues/ownership-rules/). -You can [manage code mappings through the Sentry web UI](/product/issues/suspect-commits/#set-up-code-mappings), or upload them in bulk using Sentry CLI. It is also possible to upload code mappings automatically in your CI process to keep them in sync with your repository structure. +You can [manage code mappings through the Sentry web UI](/integrations/source-code-mgmt/code-mappings/), or upload them in bulk using Sentry CLI. It is also possible to upload code mappings automatically in your CI process to keep them in sync with your repository structure. ## Permissions diff --git a/docs/concepts/key-terms/enrich-data/index.mdx b/docs/concepts/key-terms/enrich-data/index.mdx index 126206be14e658..7a1c51481a239b 100644 --- a/docs/concepts/key-terms/enrich-data/index.mdx +++ b/docs/concepts/key-terms/enrich-data/index.mdx @@ -60,11 +60,11 @@ Learn more in [Search](/concepts/search/). ### Explore -Explore is a powerful query engine that builds upon your data, allowing you to reveal patterns, anomalies, and deeper insights in the health of your entire system. With this in mind, the more (custom) data you bring into Sentry, the more flexibility you'll gain in building queries that address your environments, releases, custom development, and business characteristics. Sentry supports telemetry data from a wide range of sources, like [errors](/product/errors/), [traces and spans](/product/trace-explorer/), [logs](/product/logs/), [session replays](/product/session-replay/web/), and [application metrics](/product/metrics/). +[Explore](/product/explore/) queries your telemetry, including [errors](/product/errors/), [traces and spans](/product/trace-explorer/), [logs](/product/logs/), [session replays](/product/session-replay/web/), and [application metrics](/product/metrics/). The more custom data you send, the more specific those queries can be: environment, release, and your own tags. For instance, a Traces query can display all the spans that occurred in the _production environment_, aggregated by the _customer-type custom tag_, and ordered by _p90(span.duration)_. -Learn more in [Traces and Spans](/product/trace-explorer/). +Learn more in [Explore](/product/explore/). ### Ownership Rules diff --git a/docs/concepts/key-terms/extrapolation.mdx b/docs/concepts/key-terms/extrapolation.mdx index 9a58720d5c043e..ab5721785d4b7e 100644 --- a/docs/concepts/key-terms/extrapolation.mdx +++ b/docs/concepts/key-terms/extrapolation.mdx @@ -74,11 +74,11 @@ Extreme values like `min` and `max` aren't extrapolated because they're less sta While extrapolation is usually helpful, if you are exclusively looking to confirm your sampling usage or look exclusively at sampled data, you can turn off extrapolation. -You can disable extrapolation using the settings icon above charts in tools like Trace Explorer. Note that with extrapolation off, your metrics will only reflect the sampled data, not your full traffic. +You can disable extrapolation using the settings icon above charts in [Explore → Traces](/product/trace-explorer/). Note that with extrapolation off, your metrics will only reflect the sampled data, not your full traffic. If Sentry displays a **low confidence warning**, it means there isn't enough sampled data for reliable extrapolation. Consider increasing your sample rate or widening your query filters. -![Trace Explorer low samples warning =500x](./img/Trace_explorer_low_samples.png) +![Low sampling rate warning in Traces =500x](./img/Trace_explorer_low_samples.png) diff --git a/docs/concepts/key-terms/key-terms.mdx b/docs/concepts/key-terms/key-terms.mdx index 85b7a9dd284efe..eba65cf602d10d 100644 --- a/docs/concepts/key-terms/key-terms.mdx +++ b/docs/concepts/key-terms/key-terms.mdx @@ -54,7 +54,7 @@ Each of these key features have their own page (or set of pages) in the [sentry. - **Projects** - Lists the projects of which you're a member, by team, and provides you with a high-level overview of your projects. From here, you can go to the **Project Details** page of each project for a more granular view. Learn more in the full [Projects documentation](/product/projects/). -- **Explore** - Sentry offers multiple ways to search and investigate your application's data — including your app's [errors](/product/errors/), [traces](/product/trace-explorer/), [metrics](/product/metrics/), [profiles](/product/profiling/), [replays](/product/session-replay/), and [logs](/product/logs/) — to get the information you need to debug issues more quickly and easily. +- **[Explore](/product/explore/)** - Sentry's home to search and investigate your application's data, including [errors](/product/errors/), [traces](/product/trace-explorer/), [metrics](/product/metrics/), [profiles](/product/profiling/), [replays](/product/session-replay/), and [logs](/product/logs/). - **Pre-built Sentry Dashboards** - Sentry surfaces insights that can help you identify opportunities at the service-level to improve various parts of your app's performance, including requests, assets, caches, queues, and more. Pre-built Sentry Dashboards living under the Dashboards heading provide an overview of how your project is performing in various categories, as well as the ability to review sample events and their traces to help you diagnose potential problems. Learn more in the full [Sentry Dashboards documentation](/product/dashboards/sentry-dashboards/). diff --git a/docs/concepts/key-terms/tracing/distributed-tracing.mdx b/docs/concepts/key-terms/tracing/distributed-tracing.mdx index 11424e7d71bf9c..ccf1ae1c6ac197 100644 --- a/docs/concepts/key-terms/tracing/distributed-tracing.mdx +++ b/docs/concepts/key-terms/tracing/distributed-tracing.mdx @@ -240,6 +240,6 @@ Dynamic sampling ensures complete traces by retaining all transactions associate ## Viewing Trace Data -Use the [Trace Explorer](/product/trace-explorer/) to search for traces containing spans that meet your specific query conditions. This helps you find distributed traces that give you a connected view of your application and can help you debug and optimize your code. +Use [Explore → Traces](/product/trace-explorer/) to search for traces containing spans that meet your specific query conditions. This helps you find distributed traces that give you a connected view of your application and can help you debug and optimize your code. Through [Dashboards](/product/dashboards/sentry-dashboards/) and [Traces](/product/trace-explorer/), you can also view trace data in the [Trace View](/concepts/key-terms/tracing/trace-view/) page. diff --git a/docs/concepts/otlp/direct/claude-platform.mdx b/docs/concepts/otlp/direct/claude-platform.mdx new file mode 100644 index 00000000000000..c543d96ab5f4c4 --- /dev/null +++ b/docs/concepts/otlp/direct/claude-platform.mdx @@ -0,0 +1,71 @@ +--- +title: Claude Platform +sidebar_title: Claude Platform +sidebar_order: 30 +description: "Send OpenTelemetry traces from Claude Managed Agents and the Claude Messages API to Sentry, with no code changes." +keywords: + [ + "anthropic", + "claude", + "claude platform", + "claude console", + "claude managed agents", + "messages api", + "otlp", + "opentelemetry", + "agent tracing", + ] +--- + + + +The Claude Platform exports OpenTelemetry traces for Claude Managed Agents sessions and Messages API requests. Add Sentry as a destination in the Claude Console, and each agent turn, model request, and tool call shows up in [Agents](/product/agents/) in the same Sentry project as your errors and backend spans. You don't need to install a Sentry SDK or change any code. + +OpenTelemetry export on the Claude Platform is in beta, so span names and attributes can change. Console destinations work with the Claude API and Claude Platform on AWS. Requests sent through Amazon Bedrock or Google Cloud Vertex AI aren't traced this way. To trace those, use the Claude SDK instead (see [Trace Your Own Code](#trace-your-own-code)). + +## Prerequisites + +- A Sentry project for your agent +- The admin role in a [Claude Console](https://platform.claude.com/) organization + +## Copy Your Sentry DSN + +Go to [Project settings > Client Keys (DSN)](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/:projectId/keys/) for the project you want to send traces to, and copy the **DSN**. The Claude Console uses it to find your project's OTLP endpoint and authentication key. + +## Add Sentry as a Destination + +In the [Claude Console](https://platform.claude.com/), open the **OpenTelemetry** settings page for your organization and click **Add destination**. One destination covers both Claude Managed Agents sessions and Messages API requests. + +- **Provider**: Select **Sentry**. +- **DSN**: Paste the DSN that you copied. +- **Content mode**: Select **Full content** to see prompts, responses, and tool input and output in Sentry. Select **Metadata only** to send only timing, status, and token counts. +- **Set as organization default**: Select this for your first destination. + +![Add destination dialog in the Claude Console with Sentry selected as the provider =500x](./img/claude-platform-otel-console-sentry-destination.jpg) + +To send a workspace's traces to a different Sentry project, add a destination to that workspace. A workspace destination replaces the organization default for that workspace. + +See the [Claude Console docs](https://platform.claude.com/docs/en/manage-claude/opentelemetry#add-a-destination) for all destination options. + +## Verify Your Setup + +Send a Messages API request with an API key from a workspace that uses the destination, or run a Claude Managed Agents session. After the first traces are sent, the **Delivery** column on the Claude Console OpenTelemetry settings page changes to **Healthy**. + +Then open [**Explore > Agents**](https://sentry.io/orgredirect/organizations/:orgslug/explore/agents/) in Sentry. Your session or request shows up on the **Conversations**, **Traces**, and **LLM Calls** tabs. Select a conversation and open the **Timeline** tab to see each turn, model request, and tool call with its duration and token usage. + +![Sentry conversation timeline for a Claude Managed Agents session, showing model request and tool call spans =700x](./img/claude-platform-otel-conversation-timeline.jpg) + +The Claude Platform puts the conversation on agent spans, and tool input and output on tool spans. To read prompts and tool results, select a tool span or open the **Transcript** tab. Model request spans don't include prompts. + +## Data and Privacy + +Prompts and responses are only sent to Sentry if you select **Full content** for the destination. Sentry stores what it receives under your project's retention and [data scrubbing](/security-legal-pii/scrubbing/) settings. Spans are billed the same way as other Sentry tracing data. + +## Trace Your Own Code + +The Claude Platform export covers the requests that Claude handles. To also see your application code and the tools it runs for Claude in the same trace, instrument your app with the Claude SDK or a Sentry SDK: + +- [Trace the Claude TypeScript SDK with OpenTelemetry](https://sentry.io/cookbook/trace-claude-typescript-sdk-with-opentelemetry/) +- [Trace the Claude Python SDK with OpenTelemetry](https://sentry.io/cookbook/trace-claude-python-sdk-with-opentelemetry/) +- [Sentry Anthropic integration for JavaScript](/platforms/javascript/guides/node/configuration/integrations/anthropic/) +- [Sentry Anthropic integration for Python](/platforms/python/agent-tracing/anthropic/) diff --git a/docs/concepts/otlp/direct/img/claude-platform-otel-console-sentry-destination.jpg b/docs/concepts/otlp/direct/img/claude-platform-otel-console-sentry-destination.jpg new file mode 100644 index 00000000000000..8698cc14105c0e Binary files /dev/null and b/docs/concepts/otlp/direct/img/claude-platform-otel-console-sentry-destination.jpg differ diff --git a/docs/concepts/otlp/direct/img/claude-platform-otel-conversation-timeline.jpg b/docs/concepts/otlp/direct/img/claude-platform-otel-conversation-timeline.jpg new file mode 100644 index 00000000000000..a76c6f8d1b1582 Binary files /dev/null and b/docs/concepts/otlp/direct/img/claude-platform-otel-conversation-timeline.jpg differ diff --git a/docs/concepts/otlp/direct/index.mdx b/docs/concepts/otlp/direct/index.mdx index e9118fc006018e..cd8780dcbd77ba 100644 --- a/docs/concepts/otlp/direct/index.mdx +++ b/docs/concepts/otlp/direct/index.mdx @@ -18,3 +18,4 @@ If you need to collect data from infrastructure, transform data, or route to mul - [Traces](/concepts/otlp/direct/traces/) - Send OTel traces to Sentry - [Logs](/concepts/otlp/direct/logs/) - Send OTel logs to Sentry +- [Claude Platform](/concepts/otlp/direct/claude-platform/) - Send traces from Claude Managed Agents and the Messages API to Sentry diff --git a/docs/concepts/search/searchable-properties/events.mdx b/docs/concepts/search/searchable-properties/events.mdx index 5e3f246e714c08..11f7337bf94217 100644 --- a/docs/concepts/search/searchable-properties/events.mdx +++ b/docs/concepts/search/searchable-properties/events.mdx @@ -8,8 +8,8 @@ Events are the underlying event data captured using Sentry SDKs — that is, err You can search by event properties in the following [sentry.io](https://sentry.io) pages: -- Errors - in the query builder -- Trace Explorer - in the query builder +- Explore → Errors - in the query builder +- Explore → Traces - in the query builder - Dashboards - within the widget builder (depending on dataset selection) - Issues - as indicated in the list below - Alerts - when creating an alert diff --git a/docs/concepts/search/searchable-properties/index.mdx b/docs/concepts/search/searchable-properties/index.mdx index 952c2276d3b714..a6081df623ee01 100644 --- a/docs/concepts/search/searchable-properties/index.mdx +++ b/docs/concepts/search/searchable-properties/index.mdx @@ -4,22 +4,34 @@ description: "Learn more about searchable properties." sidebar_order: 10 --- -Sentry's search provides you with reserved keywords, like `is`, `user`, `server`, and `browser`, that you can use to search on the properties of issues, events and replays (as well as the special case of releases). You can also create [custom tags](#custom-tags) on which to search. This page provides guidance for how to use these properties and links you to the respective searchable property lists. +Search keys depend on the dataset. A key that works on Errors can be invalid on Logs. This page links each place you search to the property list for that dataset. You can also search [custom tags](#custom-tags) and any attribute you attach in the SDK. ## Search Properties -Sentry's searchable properties fall into one of five categories: +### Explore -- [Issue properties](/concepts/search/searchable-properties/issues/) -- [Event properties](/concepts/search/searchable-properties/events/) -- [Span properties](/concepts/search/searchable-properties/spans/) -- [Session Replay properties](/concepts/search/searchable-properties/session-replay/) -- [User Feedback properties](/concepts/search/searchable-properties/user-feedback/) -- [Release properties](/concepts/search/searchable-properties/releases/) +[Explore](/product/explore/) uses one search syntax and a different property list per dataset. + +- **Traces** use [span properties](/concepts/search/searchable-properties/spans/). +- **Logs** use [log properties](/concepts/search/searchable-properties/logs/). +- **Application Metrics** use [metric properties](/concepts/search/searchable-properties/metrics/). +- **Errors** use [event properties](/concepts/search/searchable-properties/events/). +- **Replays** use [session replay properties](/concepts/search/searchable-properties/session-replay/). +- **Releases** use [release properties](/concepts/search/searchable-properties/releases/). +- **Agents** use [span properties](/concepts/search/searchable-properties/spans/). Agent fields are attributes on spans. + +Profiles is a browse page. It does not have its own property list. + +### Issues and User Feedback + +Issues and User Feedback each have their own keys. + +- **Issues** uses [issue properties](/concepts/search/searchable-properties/issues/). +- **User Feedback** uses [user feedback properties](/concepts/search/searchable-properties/user-feedback/). ## Search Tips -Search terms should auto-complete, and when they don't that means you have an invalid dataset. If you enter an invalid search term and tap Return or Enter, an error message is displayed. For example, in **Errors** or **Trace Explorer**, you cannot search using a grouping function (properties with a parentheses in the key, for example `epm()`) if you don't already have a grouping function included in the "Results" table columns. +Search terms should auto-complete, and when they don't that means you have an invalid dataset. If you enter an invalid search term and tap Return or Enter, an error message is displayed. For example, in **Errors** or **Traces**, you cannot search using a grouping function (properties with a parentheses in the key, for example `epm()`) if you don't already have a grouping function included in the "Results" table columns. When you search using a property that's a function, if the key includes a parameter, you still need to add a filter or value to have a complete search token. For example, the function `count_unique(field)` takes whichever field you choose as the parameter and then you add a number as your value to filter on. So a typical search might look like: `count_unique(user):>=20`. diff --git a/docs/concepts/search/searchable-properties/logs.mdx b/docs/concepts/search/searchable-properties/logs.mdx new file mode 100644 index 00000000000000..d3cee47b936639 --- /dev/null +++ b/docs/concepts/search/searchable-properties/logs.mdx @@ -0,0 +1,209 @@ +--- +title: Log Properties +description: "Learn more about searchable log properties." +sidebar_order: 22 +--- + +Search logs in [Explore → Logs](/product/logs/). The keys below are common properties set by Sentry or the SDKs. Any custom attribute you attach on the log is searchable too, using the same attribute name you set in the SDK. + +Raw text search matches `message` only. It does not search the rest of the log. Search is case sensitive by default. Use the **Ignore case** toggle in the search bar to match regardless of case. A regular expression uses `message://pattern//`. See [regular expressions](/concepts/search/#regular-expressions-logs-only). + +## Searchable Properties + +These keys can be used in a log search: + + + +### `message` + +The log message body. + +- **Type:** string + +### `message.template` + +The parameterized template, when the SDK recorded one. For example, `Adding item {item} for user {user}`. + +- **Type:** string + +### `message.parameter.` + +One parameter from a parameterized message. `` is the parameter name or the positional index, such as `message.parameter.item` or `message.parameter.0`. + +- **Type:** string or number, depending on the value the SDK sent + +### `severity` + +The severity text. One of `trace`, `debug`, `info`, `warn`, `error`, or `fatal`. + +- **Type:** string + +### `severity_number` + +The numeric severity. Higher numbers are more severe. SDKs set the low end of each range: `trace` is 1, `debug` is 5, `info` is 9, `warn` is 13, `error` is 17, and `fatal` is 21. + +- **Type:** number + +### `timestamp` + +When the log was recorded. + +- **Type:** datetime + +### `trace` + +The trace ID for the active trace when the log was recorded. + +- **Type:** string + +### `span_id` + +The span the log was emitted from. Empty when no span was active. Older SDKs send the same value as `trace.parent_span_id`. + +- **Type:** string + +### `id` + +The log's unique ID. + +- **Type:** string + +### `project` + +The project the log belongs to. You can also scope projects with the page filter. + +- **Type:** string + +### `environment` + +The environment set in the SDK, such as `development`, `staging`, or `production`. [Learn more](/concepts/key-terms/environments/). + +- **Type:** string + +### `release` + +The release set in the SDK. `release:latest` selects the most recent release. [Learn more](/product/releases/usage/sorting-filtering/#latest-release). + +- **Type:** string + +### `logger.name` + +The name of the logger that emitted the log, when the SDK or logging integration set one. + +- **Type:** string + +### `origin` + +Set when an SDK integration captured the log. For example, `auto.log.serilog` or `auto.db.prisma`. Direct calls to the Sentry logger API do not set this. + +- **Type:** string + +### `sdk.name` + +Name of the Sentry SDK that sent the log. + +- **Type:** string + +### `sdk.version` + +Version of the Sentry SDK that sent the log. + +- **Type:** string + +### `payload_size` + +Size of the log payload, in bytes. + +- **Type:** number + +### `replay.id` + +The ID of the active replay when the log was recorded. + +- **Type:** string + +### `browser.name` + +Display name of the browser. Relay parses this from the user agent when the SDK does not set it. + +- **Type:** string + +### `browser.version` + +Version of the browser. + +- **Type:** string + +### `user.id` + +Application-specific identifier for the user. Sent when [send default PII](/platform-redirect/?next=/data-management/data-collected/) is enabled, or when you set it yourself. + +- **Type:** string + +### `user.email` + +Email address of the user. + +- **Type:** string + +### `user.name` + +Username of the user. + +- **Type:** string + +### `server.address` + +Server address. Backend SDKs attach this. + +- **Type:** string + +### `os.name` + +Operating system name. Mobile, desktop, and native SDKs attach this. + +- **Type:** string + +### `os.version` + +Operating system version. + +- **Type:** string + +### `device.brand` + +Device brand. + +- **Type:** string + +### `device.model` + +Device model. + +- **Type:** string + +### `device.family` + +Device family. + +- **Type:** string + +### `code.file.path` + +File path captured with the log, when the SDK recorded a code location. + +- **Type:** string + +### `code.function.name` + +Function name captured with the log. + +- **Type:** string + +### `code.line.number` + +Line number captured with the log. + +- **Type:** number + + diff --git a/docs/concepts/search/searchable-properties/metrics.mdx b/docs/concepts/search/searchable-properties/metrics.mdx new file mode 100644 index 00000000000000..5a6100505fb073 --- /dev/null +++ b/docs/concepts/search/searchable-properties/metrics.mdx @@ -0,0 +1,149 @@ +--- +title: Metric Properties +description: "Learn more about searchable application metric properties." +sidebar_order: 23 +--- + +Search application metrics in [Explore → Metrics](/product/metrics/). Pick the metric in the metric selector, then filter with the keys below. Any custom attribute you attach on the metric is searchable too, using the same attribute name you set in the SDK. + +The metric selector sets `metric.name`, `metric.type`, and `metric.unit` for you, so the search bar doesn't suggest those keys. + +## Searchable Properties + +These keys can be used in a metric search: + + + +### `metric.name` + +The metric identifier, such as `checkout.failed` or `queue.depth`. + +- **Type:** string + +### `metric.type` + +The metric type. One of `counter`, `gauge`, or `distribution`. + +- **Type:** string + +### `metric.unit` + +Unit of measurement, such as `millisecond`, `byte`, or `ratio`. SDKs can also send custom units. Empty or `none` when the SDK did not set one. + +- **Type:** string + +### `value` + +The numeric value. For a counter, this is the amount added. For a gauge, this is the current value. For a distribution, this is one measured value. + +- **Type:** number + +### `timestamp` + +When the metric was recorded. + +- **Type:** datetime + +### `trace` + +The trace ID for the active trace when the metric was recorded. Every metric has a trace ID, but metrics are often sampled at 100% while traces are sampled at a lower rate, so the trace itself may not have been stored. + +- **Type:** string + +### `sentry.span_id` + +The span the metric was recorded on. Empty when no span was active. + +- **Type:** string + +### `trace.parent_span_id` + +The parent span ID sent by some SDKs for the same association as `sentry.span_id`. + +- **Type:** string + +### `transaction` + +The name of the transaction or segment that was active when the metric was recorded, when the SDK set one. + +- **Type:** string + +### `id` + +The metric event's unique ID. + +- **Type:** string + +### `project` + +The project the metric belongs to. You can also scope projects with the page filter. + +- **Type:** string + +### `environment` + +The environment set in the SDK, such as `development`, `staging`, or `production`. [Learn more](/concepts/key-terms/environments/). + +- **Type:** string + +### `release` + +The release set in the SDK. [Learn more](/product/releases/). + +- **Type:** string + +### `sdk.name` + +Name of the Sentry SDK that sent the metric. + +- **Type:** string + +### `sdk.version` + +Version of the Sentry SDK that sent the metric. + +- **Type:** string + +### `replay.id` + +The ID of the active replay when the metric was recorded. + +- **Type:** string + +### `browser.name` + +Display name of the browser. Relay parses this from the user agent when the SDK does not set it. + +- **Type:** string + +### `browser.version` + +Version of the browser. + +- **Type:** string + +### `user.id` + +Application-specific identifier for the user. Sent when [send default PII](/platform-redirect/?next=/data-management/data-collected/) is enabled, or when you set it yourself. + +- **Type:** string + +### `user.email` + +Email address of the user. + +- **Type:** string + +### `user.name` + +Username of the user. + +- **Type:** string + +### `server.address` + +Server address. Backend SDKs attach this. + +- **Type:** string + + diff --git a/docs/get-started/guides/custom-spans.mdx b/docs/get-started/guides/custom-spans.mdx index 1118953c03cf7a..44d06cc77c932e 100644 --- a/docs/get-started/guides/custom-spans.mdx +++ b/docs/get-started/guides/custom-spans.mdx @@ -89,7 +89,7 @@ span.finish() transaction.finish() ``` -Numeric attributes become metrics you can aggregate with `sum()`, `avg()`, `p90()` in [Trace Explorer](https://sentry.io/orgredirect/organizations/:orgslug/explore/traces/). +Numeric attributes become metrics you can aggregate with `sum()`, `avg()`, `p90()` in [Explore → Traces](https://sentry.io/orgredirect/organizations/:orgslug/explore/traces/). ## Where to Add Spans @@ -769,4 +769,4 @@ transaction.finish() ## Next Steps -Explore the [Trace Explorer product walkthrough](/product/trace-explorer/) to learn more about the Sentry interface and discover additional tips. +See [Traces and Spans](/product/trace-explorer/) for how to query this data in Explore, and [Explore](/product/explore/) for the controls shared with other datasets. diff --git a/docs/get-started/guides/logs.mdx b/docs/get-started/guides/logs.mdx index b42b30d791a33f..4040c6ee310494 100644 --- a/docs/get-started/guides/logs.mdx +++ b/docs/get-started/guides/logs.mdx @@ -810,7 +810,7 @@ Sentry.init({ tracesSampleRate: 1.0, // 100% of traces // Capture all logs in development integrations: [ - Sentry.captureConsoleIntegration({ + Sentry.consoleLoggingIntegration({ levels: ["log", "info", "warn", "error", "debug"], }), ], @@ -851,7 +851,6 @@ Sentry.init do |config| config.dsn = '...' config.environment = 'development' config.traces_sample_rate = 1.0 # 100% of traces - config.enable_logs = true end ``` @@ -861,7 +860,6 @@ await SentryFlutter.init( options.dsn = '...'; options.environment = 'development'; options.tracesSampleRate = 1.0; // 100% of traces - options.enableLogs = true; }, appRunner: () => runApp(MyApp()), ); diff --git a/docs/get-started/guides/querying-traces.mdx b/docs/get-started/guides/querying-traces.mdx index e2fcaccf4a955d..f9b58a99be446b 100644 --- a/docs/get-started/guides/querying-traces.mdx +++ b/docs/get-started/guides/querying-traces.mdx @@ -92,5 +92,5 @@ To see an example of querying traces, check out how to query your slowest endpoi ## Next Steps -Explore the [Trace Explorer product walkthrough guides](/product/trace-explorer/) to learn more about the Sentry interface and discover additional tips. +See [Traces and Spans](/product/trace-explorer/) for how to query this data in Explore, and [Explore](/product/explore/) for the controls shared with other datasets. diff --git a/docs/get-started/index.mdx b/docs/get-started/index.mdx index caef2fb8a7a281..2e4dcc598788c3 100644 --- a/docs/get-started/index.mdx +++ b/docs/get-started/index.mdx @@ -5,11 +5,3 @@ description: "Set up Sentry and configure the key features that help you find an --- - -## Get the most out of Sentry - -1. **[Guides](/get-started/guides/)** — best practices, for what to instrument, query, and alert on -2. **[Cookbook](/get-started/cookbook/)** — full end-to-end recipes for specific jobs -3. **[Getting Started Tutorial](/product/sentry-basics/getting-started-tutorial/)** — follow the implementation of a sample fullstack Javascript app end-to-end - - diff --git a/docs/integrations/source-code-mgmt/azure-devops/img/code-mappings-stacktrace-native.png b/docs/integrations/source-code-mgmt/azure-devops/img/code-mappings-stacktrace-native.png deleted file mode 100644 index 0628a8cb9fe70d..00000000000000 Binary files a/docs/integrations/source-code-mgmt/azure-devops/img/code-mappings-stacktrace-native.png and /dev/null differ diff --git a/docs/integrations/source-code-mgmt/azure-devops/index.mdx b/docs/integrations/source-code-mgmt/azure-devops/index.mdx index 12771010540fff..54d3e45c20c822 100644 --- a/docs/integrations/source-code-mgmt/azure-devops/index.mdx +++ b/docs/integrations/source-code-mgmt/azure-devops/index.mdx @@ -112,51 +112,9 @@ When Sentry sees this, we’ll automatically annotate the matching issue with re ### Stack Trace Linking -Stack trace linking takes you from a file in your Sentry stack trace to that same file in your source code. If you have commit tracking set up in Sentry, we can take you to the exact version (using the commit associated with the event) of the source code when the error occurred. Otherwise we'll link you to the current state of the source code (using the default branch). +Stack trace linking takes you from a file in your Sentry stack trace to the same file in Azure DevOps. If you've set up commit tracking, Sentry links to the version of the file from the commit associated with the event. Otherwise, it links to the branch set in your code mapping. -1. Navigate to [**Settings > Integrations**](https://sentry.io/orgredirect/organizations/:orgslug/settings/integrations/) > **Azure DevOps > Configurations**. - -1. Click "Configure" (the gear icon) next to your Azure DevOps Instance. - -1. Click the "Code Mappings" tab. - -1. Set up a code mapping for each project you want to have stack trace linking. To create a new code mapping, click "Add Mapping". - -1. Fill out the form, then click "Save Changes". Each form field is described below: - - **Project** (required): This is the Sentry project. - - **Repo** (required): This is the Azure DevOps project associated with the Sentry project above. If you have more than one Azure DevOps project being used per Sentry project, you'll need multiple code mappings. - - **Branch** (required): This is the default branch of your code we fall back to if you do not have commit tracking set up. - - **Stack Trace Root** and **Source Code Root** (optional): See below for information on determining these values. - -#### Stack Trace Root and Source Code Root - - - -The following information is only valid for platforms which use traditional file paths. Platforms with package names require additional steps. For **Java**, read more in the [page on source context](/platforms/java/source-context/#setting-up-code-mappings). - - - -First, navigate to a stack trace that you wish to map. Find an **In App** frame, which is denoted by a bubble on the right side of the frame. The filename will be shown as the first piece of text at the left hand side of the frame header. In this example, it is `src/main.py`. - - - -For certain native platforms, the stack trace will look different. In cases like these, you can find the absolute path by hovering over the filename. - -![Highlighting where in the UI to find the file path for native stack traces](./img/code-mappings-stacktrace-native.png) - -If you aren’t sure, you can look at the event JSON by clicking on the `{}` button in the event header. Find the text in the frame's `filename` or `abs_path`. - - - -Next, locate the file seen in the stack trace with your source code provider (e.g. GitHub). In this example, the path is `flask/src/main.py` (`empower` is ignored since it is the name of the repo). - - - -Compare the file path from the stack trace with the path found in your source repository. In this example, the `src/` folder in the stack trace matches the `flask/src` folder in the source code. Using that information, set the **Stack Trace Root** to `src/` and the **Source Code Root** to `flask/src/`. This tells Sentry to replace all file paths beginning in `src/` with `flask/src/` when searching for the source code. - -For best results, we recommend always providing a non-empty value for the **Stack Trace Root** when possible. - - +To set up stack trace linking, [add a code mapping](/integrations/source-code-mgmt/code-mappings/) for each Sentry project and Azure DevOps repository you want to link. ### Source Context diff --git a/docs/integrations/source-code-mgmt/bitbucket/img/code-mappings-stacktrace-native.png b/docs/integrations/source-code-mgmt/bitbucket/img/code-mappings-stacktrace-native.png deleted file mode 100644 index 0628a8cb9fe70d..00000000000000 Binary files a/docs/integrations/source-code-mgmt/bitbucket/img/code-mappings-stacktrace-native.png and /dev/null differ diff --git a/docs/integrations/source-code-mgmt/bitbucket/index.mdx b/docs/integrations/source-code-mgmt/bitbucket/index.mdx index 61d72271bc8505..c8479c565125ef 100644 --- a/docs/integrations/source-code-mgmt/bitbucket/index.mdx +++ b/docs/integrations/source-code-mgmt/bitbucket/index.mdx @@ -177,52 +177,9 @@ When Sentry sees this, we’ll automatically annotate the matching issue with re ### Stack Trace Linking -Stack trace linking takes you from a file in your Sentry stack trace to that same file in your source code. If you have commit tracking set up in Sentry, we can take you to the exact version (using the commit associated with the event) of the source code when the error occurred. Otherwise we'll link you to the current state of the source code (using the default branch). +Stack trace linking takes you from a file in your Sentry stack trace to the same file in Bitbucket. If you've set up commit tracking, Sentry links to the version of the file from the commit associated with the event. Otherwise, it links to the branch set in your code mapping. -1. Navigate to [**Settings > Integrations**](https://sentry.io/orgredirect/organizations/:orgslug/settings/integrations/) > **Bitbucket > Configurations**. - -1. Click "Configure" (the gear icon) next to your Bitbucket Instance. - -1. Click the "Code Mappings" tab. - -1. Set up a code mapping for each project you want to have stack trace linking. To create a new code mapping, click "Add Mapping". - -1. Fill out the form, then click "Save Changes". Each form field is described below: - - - **Project** (required): This is the Sentry project. - - **Repo** (required): This is the Bitbucket project associated with the Sentry project above. If you have more than one Bitbucket project being used per Sentry project, you'll need multiple code mappings. - - **Branch** (required): This is the default branch of your code we fall back to if you do not have commit tracking set up. - - **Stack Trace Root** and **Source Code Root** (optional): See below for information on determining these values. - -#### Stack Trace Root and Source Code Root - - - -The following information is only valid for platforms which use traditional file paths. Platforms with package names require additional steps. For **Java**, read more in the [page on source context](/platforms/java/source-context/#setting-up-code-mappings). - - - -First, navigate to a stack trace that you wish to map. Find an **In App** frame, which is denoted by a bubble on the right side of the frame. The filename will be shown as the first piece of text at the left hand side of the frame header. In this example, it is `src/main.py`. - - - -For certain native platforms, the stack trace will look different. In cases like these, you can find the absolute path by hovering over the filename. - -![Highlighting where in the UI to find the file path for native stack traces](./img/code-mappings-stacktrace-native.png) - -If you aren’t sure, you can look at the event JSON by clicking on the `{}` button in the event header. Find the text in the frame's `filename` or `abs_path`. - - - -Next, locate the file seen in the stack trace with your source code provider (e.g. GitHub). In this example, the path is `flask/src/main.py` (`empower` is ignored since it is the name of the repo). - - - -Compare the file path from the stack trace with the path found in your source repository. In this example, the `src/` folder in the stack trace matches the `flask/src` folder in the source code. Using that information, set the **Stack Trace Root** to `src/` and the **Source Code Root** to `flask/src/`. This tells Sentry to replace all file paths beginning in `src/` with `flask/src/` when searching for the source code. - -For best results, we recommend always providing a non-empty value for the **Stack Trace Root** when possible. - - +To set up stack trace linking, [add a code mapping](/integrations/source-code-mgmt/code-mappings/) for each Sentry project and Bitbucket repository you want to link. ### Source Context diff --git a/docs/integrations/source-code-mgmt/code-mappings/img/code-mappings-connect-modal.png b/docs/integrations/source-code-mgmt/code-mappings/img/code-mappings-connect-modal.png new file mode 100644 index 00000000000000..903275831e7639 Binary files /dev/null and b/docs/integrations/source-code-mgmt/code-mappings/img/code-mappings-connect-modal.png differ diff --git a/docs/integrations/source-code-mgmt/code-mappings/img/code-mappings-connected-repositories.png b/docs/integrations/source-code-mgmt/code-mappings/img/code-mappings-connected-repositories.png new file mode 100644 index 00000000000000..529e46359a07b2 Binary files /dev/null and b/docs/integrations/source-code-mgmt/code-mappings/img/code-mappings-connected-repositories.png differ diff --git a/docs/integrations/source-code-mgmt/code-mappings/img/code-mappings-repositories-settings.png b/docs/integrations/source-code-mgmt/code-mappings/img/code-mappings-repositories-settings.png new file mode 100644 index 00000000000000..89af05075fb46d Binary files /dev/null and b/docs/integrations/source-code-mgmt/code-mappings/img/code-mappings-repositories-settings.png differ diff --git a/docs/integrations/source-code-mgmt/code-mappings/img/code-mappings-stacktrace-native.png b/docs/integrations/source-code-mgmt/code-mappings/img/code-mappings-stacktrace-native.png new file mode 100644 index 00000000000000..e9bfaa870fc770 Binary files /dev/null and b/docs/integrations/source-code-mgmt/code-mappings/img/code-mappings-stacktrace-native.png differ diff --git a/docs/integrations/source-code-mgmt/code-mappings/index.mdx b/docs/integrations/source-code-mgmt/code-mappings/index.mdx new file mode 100644 index 00000000000000..2c967e33e44f50 --- /dev/null +++ b/docs/integrations/source-code-mgmt/code-mappings/index.mdx @@ -0,0 +1,100 @@ +--- +title: Code Mappings +sidebar_order: 90 +description: >- + Map file paths in your stack traces to files in your repository to power + stack trace linking, suspect commits, SCM source context, and Code Owners. +--- + +Code mappings enable Sentry to turn a file path from a stack frame into a path in one of your repos. + +Code mappings power the following features: + +- **Stack trace linking**: Open the file from a stack frame in your source code provider. See the integration docs for [GitHub](/integrations/source-code-mgmt/github/#stack-trace-linking), [GitLab](/integrations/source-code-mgmt/gitlab/#stack-trace-linking), [Bitbucket](/integrations/source-code-mgmt/bitbucket/#stack-trace-linking), [Azure DevOps](/integrations/source-code-mgmt/azure-devops/#stack-trace-linking), [Perforce](/integrations/source-code-mgmt/perforce/#stack-trace-linking), and [Cursor Origin](/integrations/source-code-mgmt/cursor-origin/#stack-trace-linking) for provider-specific instructions. +- **[Suspect commits](/product/issues/suspect-commits/)**: Find the most recent code change in a stack trace. +- **[SCM source context](/integrations/source-code-mgmt/source-context/)**: Fetch the lines around a frame from your repo when the event doesn't include them. +- **[Code Owners](/product/issues/ownership-rules/#code-owners)**: Import a CODEOWNERS file and sync it to stack trace paths. + +To get started with code mappings, install a [source code management integration](/integrations/source-code-mgmt/) and add the repo you want to map. This page covers path configuration only; installation, commit tracking, and resolving issues via commit are discussed in detail on each integration's page. + +## Where to Configure Code Mappings + +A code mapping connects a Sentry project to a single repo, with one or more paths. You can create a connection from either the project or the repo; both open the same modal. + +- **From a project**: Go to your project's [**General Settings**](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/:projectId/), find **Connected Repositories**, and click on **Connect repository**. The project will already be selected. + + ![The Connected Repositories panel in a project's General Settings, with the Connect repository button highlighted](./img/code-mappings-connected-repositories.png) + +- **From a repo**: Go to [**Settings > Repositories**](https://sentry.io/orgredirect/organizations/:orgslug/settings/repos/) and click **+** on the repo's row. The repo will already be selected. To change an existing connection, click the project's chip on the repo's row. + + ![The Repositories page in organization settings, with the plus button on a repository row highlighted](./img/code-mappings-repositories-settings.png) + +To map more than one path between the same project and repo, click on **Add another path**. When you save, Sentry will apply every path in the connection at once. + +If a project uses code from more than one repo, create a separate connection for each one. + +## Path Fields + +Each path in a connection has three fields: + +- **Branch**: The branch Sentry uses when the event isn't associated with a release commit. If you've set up [commit tracking](/product/releases/associate-commits/), Sentry will use the release's commit instead. +- **Stack trace prefix**: The beginning of the file path as it appears in your stack trace. Previously this field was named **Stack Trace Root**. +- **Repository prefix**: The path that replaces the stack trace prefix when Sentry looks up the file in your repo. Previously this field was named **Source Code Root**. + +![The Connect a repository modal, showing the Branch, Stack trace prefix, and Repository prefix fields above an example preview](./img/code-mappings-connect-modal.png) + +As you fill in the prefixes, **Example preview** shows how a sample path from your stack trace will be rewritten to point at your repo. + +An empty **Stack trace prefix** will match every file in the stack trace. If a project has more than one path, set a specific prefix for each so that Sentry knows which path applies to which files. + +## Find Your Prefixes + + + +These steps only apply to platforms that use file paths in stack traces. Platforms that use package names require extra steps. See [Platform-Specific Paths](#platform-specific-paths). + + + +Open a stack trace you want to map, then find an **In App** frame. In App frames have a label on the right side of the frame. The filename is the first text on the left side of the frame header. For this example, the filename is `src/main.py`. + + + +Stack traces from some native platforms may look different. Hover over the filename to see the absolute path. + +![Where to find the file path in a native stack trace](./img/code-mappings-stacktrace-native.png) + +If you're unsure of which path to use, click `{}` in the event header to open the event JSON and find the frame's `filename` or `abs_path`. + + + +Next, find the same file in your repo. In this example, the path is `flask/src/main.py`. Leave out the repo name (`empower`). + + + +Compare the two paths. Here, `src/` in the stack trace matches `flask/src/` in the repo, so set: + +- **Stack trace prefix**: `src/` +- **Repository prefix**: `flask/src/` + +Sentry then replaces `src/` with `flask/src/` at the start of every matching stack trace path when it looks up the file. + +## How to Edit a Code Mapping + +To edit a connection, you can access it from either entry point. The modal opens with the project and repo locked and the existing paths all filled in. From here, you can change paths, add paths, and save your changes. + +If a path is used by a [Code Owners](/product/issues/ownership-rules/#code-owners) import, you can't change its prefixes until you remove that Code Owners import. + +## Automatic Code Mappings + +If your organization has the [GitHub integration](/integrations/source-code-mgmt/github/) installed, Sentry tries to create code mappings automatically for JavaScript, Python, Java, PHP, Ruby, Go, C#, and Kotlin projects. You can still add or edit mappings yourself. + +## Bulk Upload + +To create several code mappings in one go, upload them with the [Sentry CLI](/cli/code-mappings/). The CLI's JSON format uses `stackRoot` for the stack trace prefix and `sourceRoot` for the repository prefix. + +## Platform-Specific Paths + +Some platforms don't put repository-style file paths in their stack traces: + +- **Java**: Stack traces use package names. See [Java Source Context](/platforms/java/source-context/#setting-up-code-mappings) to work out the prefixes. +- **Godot**: Stack traces use `res://` paths. See [Godot Source Context](/platforms/godot/configuration/source-context/). diff --git a/docs/integrations/source-code-mgmt/cursor-origin/index.mdx b/docs/integrations/source-code-mgmt/cursor-origin/index.mdx index c62a86a3996fa4..8cb6113c1ec657 100644 --- a/docs/integrations/source-code-mgmt/cursor-origin/index.mdx +++ b/docs/integrations/source-code-mgmt/cursor-origin/index.mdx @@ -32,19 +32,7 @@ If you have added [Seer](/product/ai-in-sentry/seer/) to your organization, you Stack trace linking takes you from a stack frame in Sentry to the corresponding file and line in Origin. With commit tracking configured, Sentry can link to the version associated with the event's release. Otherwise, it uses the branch configured in your code mapping. -1. Go to [**Settings > Integrations**](https://sentry.io/orgredirect/organizations/:orgslug/settings/integrations/) and open your **Cursor Origin** installation's configuration. -2. Select the **Code Mappings** tab, then click **Add Mapping**. -3. Fill out the mapping: - - **Project**: The Sentry project whose stack traces you want to link. - - **Repo**: The Origin repository containing the project's source code. - - **Branch**: The fallback branch to use when release commit information isn't available. - - **Stack Trace Root**: The path prefix shown in your stack traces. - - **Source Code Root**: The corresponding path prefix in your repository. -4. Click **Save Changes**. Add a mapping for each project and repository combination you need. - -For example, if a stack frame shows `src/main.py` but the repository path is `backend/src/main.py`, set **Stack Trace Root** to `src/` and **Source Code Root** to `backend/src/`. - -For platforms that use package names instead of file paths, additional configuration may be required. For Java, see [setting up code mappings](/platforms/java/source-context/#setting-up-code-mappings). +To set up stack trace linking, [add a code mapping](/integrations/source-code-mgmt/code-mappings/) for each Sentry project and Origin repository you want to link. ### Code Owners @@ -60,7 +48,7 @@ Import your Origin CODEOWNERS file to automatically assign Sentry issues based o /frontend/ frontend-owner@example.com ``` -1. Set up [code mappings](#stack-trace-linking) for your project. +1. Set up [code mappings](/integrations/source-code-mgmt/code-mappings/) for your project. 2. Add a CODEOWNERS file to your repository at `CODEOWNERS`, `.github/CODEOWNERS`, or `docs/CODEOWNERS`. 3. Go to your project's [**Ownership Rules**](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/:projectId/ownership/) settings and import the CODEOWNERS file, selecting the code mapping to apply. During import, Sentry uses the first file it finds in the order listed above. @@ -90,6 +78,6 @@ Sentry adds a reference to the commit or pull request on the matching issue. Whe If a repository is missing, check that the Origin installation has access to it, then refresh the integration's configuration in Sentry. -If a stack trace link points to the wrong file, compare the frame's file path with the path in Origin and check your code mapping's **Stack Trace Root**, **Source Code Root**, and **Branch**. +If a stack trace link points to the wrong file, compare the frame's file path with the path in Origin and check your code mapping's **Stack trace prefix**, **Repository prefix**, and **Branch**. If CODEOWNERS rules don't assign issues, confirm that the email addresses belong to users in your Sentry organization, that those users have project access, and that the selected code mapping matches the stack trace paths. diff --git a/docs/integrations/source-code-mgmt/github/img/code-mappings-stacktrace-native.png b/docs/integrations/source-code-mgmt/github/img/code-mappings-stacktrace-native.png deleted file mode 100644 index 0628a8cb9fe70d..00000000000000 Binary files a/docs/integrations/source-code-mgmt/github/img/code-mappings-stacktrace-native.png and /dev/null differ diff --git a/docs/integrations/source-code-mgmt/github/index.mdx b/docs/integrations/source-code-mgmt/github/index.mdx index be919509b7be73..33bf62cee84571 100644 --- a/docs/integrations/source-code-mgmt/github/index.mdx +++ b/docs/integrations/source-code-mgmt/github/index.mdx @@ -417,7 +417,7 @@ When a pull request is opened, Sentry will parse the filenames and function name Sentry will comment on the pull request with up to five issues per file that were first seen within the past 90 days and were last seen within the past 14 days. -This feature requires [code mappings](/product/issues/suspect-commits/#2-set-up-code-mappings) and is currently only supported for Python, JavaScript/TypeScript, PHP, and Ruby files. If you're using a different language, [let us know on this GitHub ticket](https://github.com/getsentry/sentry/issues/69824). For JavaScript/TypeScript, please ensure that you've unminified your code by [setting up source maps](/platforms/javascript/sourcemaps/). +This feature requires [code mappings](/integrations/source-code-mgmt/code-mappings/) and is currently only supported for Python, JavaScript/TypeScript, PHP, and Ruby files. If you're using a different language, [let us know on this GitHub ticket](https://github.com/getsentry/sentry/issues/69824). For JavaScript/TypeScript, please ensure that you've unminified your code by [setting up source maps](/platforms/javascript/sourcemaps/). ### Missing Member Detection @@ -437,57 +437,9 @@ By default, this feature is automatically enabled once your GitHub integration h ### Stack Trace Linking - - -Sentry will automatically try to set up code mappings on JavaScript, Python, Java, PHP, Ruby, Go, C#, and Kotlin for organizations with the GitHub integration installed. If your project uses a different SDK, you can add code mappings manually. You can also [upload code mappings in bulk via the CLI](/cli/code-mappings/). - - - -Stack trace linking takes you from a file in your Sentry stack trace to that same file in your source code. If you have commit tracking set up in Sentry, we can take you to the exact version (using the commit associated with the event) of the source code when the error occurred. Otherwise we'll link you to the current state of the source code (using the default **branch**). - -1. Navigate to [**Settings > Integrations**](https://sentry.io/orgredirect/organizations/:orgslug/settings/integrations/) > **GitHub > Configurations**. - -1. Click the "Configure" button next to your GitHub Instance. - -1. Click the **Code Mappings** tab. - -1. Set up a code mapping for each project for which you want to enable stack trace linking. To create a new code mapping, click **Add Mapping**. - -1. Fill out the form, then click **Save Changes**. Each form field is described below: - - **Project** (required): This is the Sentry project. - - **Repo** (required): This is the GitHub repository associated with the Sentry project above. If you have more than one GitHub repository being used per Sentry project, you'll need multiple code mappings. - - **Branch** (required): This is the default branch of your code we fall back to if you do not have commit tracking set up. - - **Stack Trace Root** and **Source Code Root** (optional): See below for information on determining these values. - -#### Stack Trace Root and Source Code Root - - - -The following information is only valid for platforms which use traditional file paths. Platforms with package names require additional steps. For **Java**, read more in the [page on source context](/platforms/java/source-context/#setting-up-code-mappings). - - - -First, navigate to a stack trace that you wish to map. Find an **In App** frame, which is denoted by a bubble on the right side of the frame. The filename will be shown as the first piece of text at the left hand side of the frame header. In this example, it is `src/main.py`. - - - -For certain native platforms, the stack trace will look different. In cases like these, you can find the absolute path by hovering over the filename. - -![Highlighting where in the UI to find the file path for native stack traces](./img/code-mappings-stacktrace-native.png) - -If you aren't sure, you can look at the event JSON by clicking on the `{}` button in the event header. Find the text in the frame's `filename` or `abs_path`. - - - -Next, locate the file seen in the stack trace with your source code provider (e.g. GitHub). In this example, the path is `flask/src/main.py` (`empower` is ignored since it is the name of the repo). - - - -Compare the file path from the stack trace with the path found in your source repository. In this example, the `src/` folder in the stack trace matches the `flask/src` folder in the source code. Using that information, set the **Stack Trace Root** to `src/` and the **Source Code Root** to `flask/src/`. This tells Sentry to replace all file paths beginning in `src/` with `flask/src/` when searching for the source code. - -For best results, we recommend always providing a non-empty value for the **Stack Trace Root** when possible. +Stack trace linking takes you from a file in your Sentry stack trace to the same file in GitHub. If you've set up commit tracking, Sentry links to the version of the file from the commit associated with the event. Otherwise, it links to the branch set in your code mapping. - +To set up stack trace linking, [add a code mapping](/integrations/source-code-mgmt/code-mappings/) for each Sentry project and GitHub repository you want to link. ### Source Context diff --git a/docs/integrations/source-code-mgmt/gitlab/img/code-mappings-stacktrace-native.png b/docs/integrations/source-code-mgmt/gitlab/img/code-mappings-stacktrace-native.png deleted file mode 100644 index 0628a8cb9fe70d..00000000000000 Binary files a/docs/integrations/source-code-mgmt/gitlab/img/code-mappings-stacktrace-native.png and /dev/null differ diff --git a/docs/integrations/source-code-mgmt/gitlab/index.mdx b/docs/integrations/source-code-mgmt/gitlab/index.mdx index 4c718b7d7b82ff..cae3640f8e8ce3 100644 --- a/docs/integrations/source-code-mgmt/gitlab/index.mdx +++ b/docs/integrations/source-code-mgmt/gitlab/index.mdx @@ -126,52 +126,9 @@ A `` may look something like 'BACKEND-C' in the image below. ### Stack Trace Linking -Stack trace linking takes you from a file in your Sentry stack trace to that same file in your source code. If you have commit tracking set up in Sentry, we can take you to the exact version (using the commit associated with the event) of the source code when the error occurred. Otherwise we'll link you to the current state of the source code (using the default **branch**). +Stack trace linking takes you from a file in your Sentry stack trace to the same file in GitLab. If you've set up commit tracking, Sentry links to the version of the file from the commit associated with the event. Otherwise, it links to the branch set in your code mapping. -1. Navigate to [**Settings > Integrations**](https://sentry.io/orgredirect/organizations/:orgslug/settings/integrations/) > **GitLab > Configurations**. - -1. Click the "Configure" button next to your GitLab Instance. - -1. Click the **Code Mappings** tab. - -1. Set up a code mapping for each project for which you want to enable stack trace linking. To create a new code mapping, click **Add Mapping**. - -1. Fill out the form, then click **Save Changes**. Each form field is described below: - - - **Project** (required): This is the Sentry project. - - **Repo** (required): This is the GitLab project associated with the Sentry project above. If you have more than one GitLab project being used per Sentry project, you'll need multiple code mappings. - - **Branch** (required): This is the default branch of your code we fall back to if you do not have commit tracking set up. - - **Stack Trace Root** and **Source Code Root** (optional): See below for information on determining these values. - -#### Stack Trace Root and Source Code Root - - - -The following information is only valid for platforms which use traditional file paths. Platforms with package names (such as **Java**, **Cocoa**, and **Flutter**) require additional steps. - - - -First, navigate to a stack trace that you wish to map. Find an **In App** frame, which is denoted by a bubble on the right side of the frame. The filename will be shown as the first piece of text at the left hand side of the frame header. In this example, it is `src/main.py`. - - - -For certain native platforms, the stack trace will look different. In cases like these, you can find the absolute path by hovering over the filename. - -![Highlighting where in the UI to find the file path for native stack traces =600x](./img/code-mappings-stacktrace-native.png) - -If you aren’t sure, you can look at the event JSON by clicking on the `{}` button in the event header. Find the text in the frame's `filename` or `abs_path`. - - - -Next, locate the file seen in the stack trace with your source code provider (e.g. GitHub). In this example, the path is `flask/src/main.py` (`empower` is ignored since it is the name of the repo). - - - -Compare the file path from the stack trace with the path found in your source repository. In this example, the `src/` folder in the stack trace matches the `flask/src` folder in the source code. Using that information, set the **Stack Trace Root** to `src/` and the **Source Code Root** to `flask/src/`. This tells Sentry to replace all file paths beginning in `src/` with `flask/src/` when searching for the source code. - -For best results, we recommend always providing a non-empty value for the **Stack Trace Root** when possible. - - +To set up stack trace linking, [add a code mapping](/integrations/source-code-mgmt/code-mappings/) for each Sentry project and GitLab repository you want to link. ### Source Context diff --git a/docs/integrations/source-code-mgmt/index.mdx b/docs/integrations/source-code-mgmt/index.mdx index 79759458d95504..37c525ae0e26eb 100644 --- a/docs/integrations/source-code-mgmt/index.mdx +++ b/docs/integrations/source-code-mgmt/index.mdx @@ -14,4 +14,5 @@ description: "Learn more about Sentry's source code management integrations." ## Features +- [Code Mappings](/integrations/source-code-mgmt/code-mappings/) — map stack-trace file paths to files in your repository. Required for stack trace linking, suspect commits, SCM source context, and Code Owners. - [SCM Source Context](/integrations/source-code-mgmt/source-context/) — render source lines around each stack-trace frame on demand from your SCM provider, for events that don't carry inline source context. diff --git a/docs/integrations/source-code-mgmt/perforce/index.mdx b/docs/integrations/source-code-mgmt/perforce/index.mdx index 57e730d93b2a36..588e94fa211b45 100644 --- a/docs/integrations/source-code-mgmt/perforce/index.mdx +++ b/docs/integrations/source-code-mgmt/perforce/index.mdx @@ -89,34 +89,14 @@ If you have a P4 Code Review (Swarm) URL configured, links will open in the Swar #### Setting Up Code Mappings -1. Navigate to [**Settings > Integrations**](https://sentry.io/orgredirect/organizations/:orgslug/settings/integrations/) > **Perforce > Configurations**. +To set up stack trace linking, [add a code mapping](/integrations/source-code-mgmt/code-mappings/) for each Sentry project and Perforce depot you want to link. For Perforce, **Branch** is the stream name. It's optional, because streams are part of the depot path. -2. Click the gear icon next to your Perforce instance, then click the **Code Mappings** tab. + -3. Click **Add Mapping** and fill out the form: - - - **Project** (required): The Sentry project to map. - - **Repo** (required): The Perforce depot associated with this project. - - **Branch**: Stream name (optional for Perforce — streams are part of the depot path). - - **Stack Trace Root** and **Source Code Root** (optional): See below. - -#### Stack Trace Root and Source Code Root - - - -The following information is only valid for platforms which use traditional file paths. Platforms with package names require additional steps. +If the stack trace shows `src/main.cpp` and the depot path is `//depot/project/src/main.cpp`, set **Stack trace prefix** to `src/` and **Repository prefix** to `project/src/`. Sentry then replaces `src/` with `project/src/` when it looks up files in your depot. -Find an **In App** frame in your stack trace. The filename (e.g., `src/main.cpp`) is shown in the frame header. Compare this to the path in your Perforce depot (e.g., `//depot/project/src/main.cpp`). - -If the stack trace shows `src/main.cpp` and the depot path is `//depot/project/src/main.cpp`, set: - -- **Stack Trace Root**: `src/` -- **Source Code Root**: `project/src/` - -This tells Sentry to replace `src/` with `project/src/` when locating source files in your depot. - ### Source Context If your events don't carry inline source context (for example, native crashes or releases built without source maps), you can have Sentry fetch the surrounding lines from your Perforce depot on demand and render them in the issue stack trace. See [SCM Source Context](/integrations/source-code-mgmt/source-context/) for setup and access details. diff --git a/docs/integrations/source-code-mgmt/source-context/index.mdx b/docs/integrations/source-code-mgmt/source-context/index.mdx index eece6468faf353..7db70ca5c39bde 100644 --- a/docs/integrations/source-code-mgmt/source-context/index.mdx +++ b/docs/integrations/source-code-mgmt/source-context/index.mdx @@ -20,7 +20,7 @@ This is the same context view you see on events that *do* carry inline source, b - [GitHub / GitHub Enterprise](/integrations/source-code-mgmt/github/) - [GitLab](/integrations/source-code-mgmt/gitlab/) - [Perforce](/integrations/source-code-mgmt/perforce/) -- A code mapping configured for each project where you want SCM source context. See the **Stack Trace Linking** section of your provider's page for setup instructions. +- A code mapping configured for each project where you want SCM source context. See [Code Mappings](/integrations/source-code-mgmt/code-mappings/) for setup instructions. ## Enable diff --git a/docs/organization/authentication/sso/index.mdx b/docs/organization/authentication/sso/index.mdx index c264f4c58b1773..dc8d7f1c694cdf 100644 --- a/docs/organization/authentication/sso/index.mdx +++ b/docs/organization/authentication/sso/index.mdx @@ -179,3 +179,9 @@ System for Cross-Domain Identity Management ([SCIM](http://www.simplecloud.info/ - [Okta SCIM Setup](/organization/authentication/sso/okta-sso/okta-scim/) - [Azure AD SCIM Setup](/organization/authentication/sso/azure-sso/#scim-integration) - If your Provider is not listed here, SCIM may be supported as it is a common standard. If you are having issues please contact our support team. + +### SCIM 2.0 Service Discovery + +Sentry supports the SCIM 2.0 service discovery endpoints defined in [Section 4 of RFC 7644](https://datatracker.ietf.org/doc/html/rfc7644#section-4): `ServiceProviderConfig`, `ResourceTypes`, and `Schemas`. They're available under your SCIM URL, require the same Auth Token as the rest of the SCIM API, and need no additional setup. + +Identity Governance and Administration (IGA) platforms, such as SailPoint IdentityIQ, require these endpoints to connect and use them to discover which SCIM features and attributes Sentry supports. For request and response details, see the [SCIM API documentation](/api/scim/). diff --git a/docs/organization/authentication/sso/saml2.mdx b/docs/organization/authentication/sso/saml2.mdx index 5c998ab2fd2ccc..bbbce5f6cd03db 100644 --- a/docs/organization/authentication/sso/saml2.mdx +++ b/docs/organization/authentication/sso/saml2.mdx @@ -136,7 +136,7 @@ Because Sentry uses Just-In-Time (JIT) provisioning, new members are registered ## SCIM Provisioning -SCIM is available for automatic user provisioning, deprovisioning, and team assignment for SAML2 IdPs. [Configure Sentry for SCIM](/organization/authentication/sso/okta-sso/okta-scim/#sentry-configuration), and then follow your IdP's documentation for further setup. Learn more about the Sentry SCIM API endpoints in the [SCIM API documentation](/api/scim/). +SCIM is available for automatic user provisioning, deprovisioning, and team assignment for SAML2 IdPs. [Configure Sentry for SCIM](/organization/authentication/sso/okta-sso/okta-scim/#sentry-configuration), and then follow your IdP's documentation for further setup. Learn more about the Sentry SCIM API endpoints in the [SCIM API documentation](/api/scim/). If you connect an identity governance platform, such as SailPoint IdentityIQ, see [SCIM 2.0 Service Discovery](/organization/authentication/sso/#scim-20-service-discovery). ## FAQ diff --git a/docs/organization/data-storage-location/index.mdx b/docs/organization/data-storage-location/index.mdx index 0a6fe51bb530a5..21c9d52120adfb 100644 --- a/docs/organization/data-storage-location/index.mdx +++ b/docs/organization/data-storage-location/index.mdx @@ -16,10 +16,10 @@ Your selection determines your data storage location only. Sentry will continue The table below shows the location where your data will be stored at rest, based on your selection. -| **Data Storage Location** | **Region** | **Physical Location** | -| ----------------------------- | ---------- | ---------------------- | -| United States of America (US) | US | Iowa, USA | -| European Union (EU) | EU | Frankfurt, Germany | +| **Data Storage Location** | **Region** | **Physical Location** | +| ----------------------------- | ---------- | --------------------- | +| United States of America (US) | US | Iowa, USA | +| European Union (EU) | EU | Frankfurt, Germany | ## What Types of Data Are Stored Where @@ -90,6 +90,17 @@ For [data stored in the US](#data-stored-in-us), your API domain should be `sent At this time, your data storage location can’t be changed if you have an existing SaaS organization. The only way to switch it is by creating a new organization. +Sentry doesn't move data or settings between SaaS organizations. Historical data, like issues, events, replays, and source maps, stays in your existing organization. + + + +- **Setup:** Recreate teams, projects, members, [SSO](/organization/authentication/sso/), [integrations](/integrations/), [alerts](/product/monitors-and-alerts/), and [dashboards](/product/dashboards/) in the new organization. +- **SDKs and tooling:** Update [DSNs](/concepts/key-terms/dsn-explainer/), auth tokens, org slugs, and [API domains](#using-data-storage-location-apis) in your apps and CI. +- **Cutover:** Keep the old organization until new events and alerts work, and until you no longer need its history. +- **Billing:** Each organization has its own subscription. [Cancellations](/pricing/#plans-and-free-trials) take effect at the end of the current contract cycle and aren't refunded, so plan the cutover around your renewal date. + + + ### Self-hosted If you have a self-hosted Sentry account, you can [follow these instructions](/concepts/migration/) to migrate your data. diff --git a/docs/platforms/apple/common/configuration/metric-kit.mdx b/docs/platforms/apple/common/configuration/metric-kit.mdx index d2652c8c99df23..89d8c5f080178c 100644 --- a/docs/platforms/apple/common/configuration/metric-kit.mdx +++ b/docs/platforms/apple/common/configuration/metric-kit.mdx @@ -9,7 +9,7 @@ and [MXCPUExceptionDiagnostic](https://developer.apple.com/documentation/metrick This feature is available on Cocoa 8.14.0 and up. The SDK supports this feature from iOS 15 and up and macOS 12 and up because in these versions, MetricKit delivers diagnostic reports immediately, which allows the Sentry SDK to apply current data from the scope. -Note that the Cocoa SDK has no control over the stack traces provided by MetricKit. Some only offer a couple of frames. If these aren't useful to you, you can drop them in `beforeSend`. +Note that the Cocoa SDK has no control over the stack traces provided by MetricKit. Some only offer a couple of frames. If these aren't useful to you, you can drop them in `beforeSend`. You can identify MetricKit events by looking at the `mx_hang_diagnostic`, `mx_cpu_exception`, and `mx_disk_write_exception` `mechanism.type`. diff --git a/docs/platforms/apple/guides/ios/features/index.mdx b/docs/platforms/apple/guides/ios/features/index.mdx index 3193376e5953b0..51af985af7a378 100644 --- a/docs/platforms/apple/guides/ios/features/index.mdx +++ b/docs/platforms/apple/guides/ios/features/index.mdx @@ -1,6 +1,7 @@ --- title: Features sidebar_order: 1 +sidebar_hidden: true description: "Learn about Sentry's Apple SDK features for iOS." --- diff --git a/docs/platforms/apple/guides/tvos/features/index.mdx b/docs/platforms/apple/guides/tvos/features/index.mdx index 76eb45b6b8bbfd..b043c6a8c4985f 100644 --- a/docs/platforms/apple/guides/tvos/features/index.mdx +++ b/docs/platforms/apple/guides/tvos/features/index.mdx @@ -1,6 +1,7 @@ --- title: Features sidebar_order: 1 +sidebar_hidden: true description: "Learn about Sentry's Apple SDK features for tvOS." --- diff --git a/docs/platforms/apple/guides/visionos/features/index.mdx b/docs/platforms/apple/guides/visionos/features/index.mdx index e5c46af0da4f12..bbaca278f22506 100644 --- a/docs/platforms/apple/guides/visionos/features/index.mdx +++ b/docs/platforms/apple/guides/visionos/features/index.mdx @@ -1,6 +1,7 @@ --- title: Features sidebar_order: 1 +sidebar_hidden: true description: "Learn about Sentry's Apple SDK features for visionOS." --- diff --git a/docs/platforms/dart/guides/flutter/index.mdx b/docs/platforms/dart/guides/flutter/index.mdx index 236116b398d18e..95d9486c7c9555 100644 --- a/docs/platforms/dart/guides/flutter/index.mdx +++ b/docs/platforms/dart/guides/flutter/index.mdx @@ -124,7 +124,7 @@ Our next recommended steps for you are: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup - Continue to customize your configuration -- Add readable stack traces to errors +- Add readable stack traces to errors - Learn about the features of Sentry's Flutter SDK - Add performance instrumentation to your app diff --git a/docs/platforms/dart/guides/flutter/manual-setup.mdx b/docs/platforms/dart/guides/flutter/manual-setup.mdx index 29fb4440898c64..01831e8b2c5d4c 100644 --- a/docs/platforms/dart/guides/flutter/manual-setup.mdx +++ b/docs/platforms/dart/guides/flutter/manual-setup.mdx @@ -130,7 +130,7 @@ Our next recommended steps for you are: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup - Continue to customize your configuration -- Add readable stack traces to errors +- Add readable stack traces to errors - Learn about the features of Sentry's Flutter SDK - Add performance instrumentation to your app diff --git a/docs/platforms/dotnet/common/metrics/index.mdx b/docs/platforms/dotnet/common/metrics/index.mdx index 6363af6ef13e69..01a94054b9d7b2 100644 --- a/docs/platforms/dotnet/common/metrics/index.mdx +++ b/docs/platforms/dotnet/common/metrics/index.mdx @@ -5,6 +5,8 @@ description: "Metrics allow you to send, view and query counters, gauges and mea sidebar_order: 3 sidebar_section: features new: true +notSupported: + - dotnet.xamarin --- diff --git a/docs/platforms/dotnet/guides/android/index.mdx b/docs/platforms/dotnet/guides/android/index.mdx index a22d3c50e18138..275826bcbcc2c7 100644 --- a/docs/platforms/dotnet/guides/android/index.mdx +++ b/docs/platforms/dotnet/guides/android/index.mdx @@ -6,20 +6,6 @@ description: "Learn about Sentry's .NET integration with .NET for Android" Sentry supports [.NET for Android](https://learn.microsoft.com/dotnet/android/getting-started/installation/) directly from the [Sentry NuGet package](https://www.nuget.org/packages/Sentry). -## Overview of the features - -- All the features of our main [.NET SDK](/platforms/dotnet/), for your managed code -- Attach LogCat logs to events -- Java crash reporting for Android, leveraging our [Android SDK](/platforms/android/) including: - - [Capture Application Not Responding (ANR) errors](/platforms/android/configuration/app-not-respond/) when the app is unresponsive - - Automatically [attach screenshots to Java exceptions](/platforms/android/enriching-events/screenshots/) - - Automatic breadcrumbs for Activity lifecycle, App lifecycle, System and Network events and User Interactions - - Automatic [Activity lifecycle tracing](/platforms/android/tracing/instrumentation/automatic-instrumentation/#activity-instrumentation) and [User Interaction tracing](/platforms/android/performance/instrumentation/automatic-instrumentation/#user-interaction-instrumentation) - - Device Root checking -- Native crash reporting for Android, leveraging our [Android NDK](/platforms/android/configuration/using-ndk/) -- Automatic session tracking and [release health](/product/releases/) -- _Session Replay for Android_ (currently experimental) - ## Install Add the Sentry dependency to your .NET for Android application: @@ -34,8 +20,31 @@ Install-Package Sentry -Version {{@inject packages.version('sentry.dotnet') }} ## Configure +**Error Monitoring** starts working as soon as you call `SentrySdk.Init()`. **Logs** sent through `SentrySdk.Logger` and **Application Metrics** need no extra configuration. You'll learn how to send them in [Send Logs](#send-logs) and [Send Application Metrics](#send-application-metrics-). + +This guide also enables **Tracing** and **Session Replay** (experimental). + +On .NET for Android, you also get: + +- All the features of our main [.NET SDK](/platforms/dotnet/), for your managed code +- LogCat logs attached to events +- Java crash reporting for Android, leveraging our [Android SDK](/platforms/android/) including: + - [Capture Application Not Responding (ANR) errors](/platforms/android/configuration/app-not-respond/) when the app is unresponsive + - Automatically [attach screenshots to Java exceptions](/platforms/android/enriching-events/screenshots/) + - Automatic breadcrumbs for Activity lifecycle, App lifecycle, System and Network events and User Interactions + - Automatic [Activity lifecycle tracing](/platforms/android/tracing/instrumentation/automatic-instrumentation/#activity-instrumentation) and [User Interaction tracing](/platforms/android/tracing/instrumentation/automatic-instrumentation/#user-interaction-instrumentation) + - Device Root checking +- Native crash reporting for Android, leveraging our [Android NDK](/platforms/android/configuration/using-ndk/) +- Automatic session tracking and [release health](/product/releases/) + In your `MainActivity.cs` file, call `SentrySdk.Init` in the `OnCreate` event and include any options you would like to set. The `Dsn` is the only required parameter. +The snippet also turns on: + +- Tracing: via `TracesSampleRate` +- Session Replay: via `Native.ExperimentalOptions.SessionReplay` + +Don't need a feature? Remove its options from the snippet. ```csharp [Activity(Label = "@string/app_name", MainLauncher = true)] @@ -47,6 +56,10 @@ public class MainActivity : Activity { options.Dsn = "___PUBLIC_DSN___"; options.SendDefaultPii = true; // adds the user's IP address automatically + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. + options.TracesSampleRate = 1.0; #if DEBUG // Log debug information about the Sentry SDK options.Debug = true; @@ -67,8 +80,6 @@ public class MainActivity : Activity // Session Replay is currently available via the ExperimentalOptions options.Native.ExperimentalOptions.SessionReplay.OnErrorSampleRate = 1.0; options.Native.ExperimentalOptions.SessionReplay.SessionSampleRate = 1.0; - options.Native.ExperimentalOptions.SessionReplay.MaskAllImages = false; - options.Native.ExperimentalOptions.SessionReplay.MaskAllText = false; options.SetBeforeSend(evt => { @@ -95,7 +106,7 @@ The .NET for Android integration is part of [Sentry](/platforms/dotnet/). Please Android-specific options are described below. For configuration of the embedded Sentry Android SDK, see Android Native Options. -### LogCatIntegration +#### LogCatIntegration Can be set to control whether when LogCat logs are attached to events. It can be set to one of the following values: @@ -112,18 +123,53 @@ Use caution when enabling `LogCatIntegrationType.All`, as this may result in a l -### LogCatMaxLines +#### LogCatMaxLines The maximum number of lines to read from LogCat logs. The default value is 1000. -## Verify +## Send Logs + +Use `SentrySdk.Logger` to send logs at different levels. These logs are sent without an additional option. + +See Set Up Logs for all available logging methods and formatting options. + +```csharp +SentrySdk.Logger.LogInfo("Order processed"); +SentrySdk.Logger.LogWarning("Rate limit reached for /api/orders"); +``` + +## Send Application Metrics -This snippet includes an intentional error, so you can test that everything is working as soon as you set it up. +Metrics are enabled by default in Sentry .NET SDK 6.1.0 and later. Use `SentrySdk.Metrics` to send counters, gauges, and distributions from your app. + +See Set Up Metrics for all available metric types and configuration options. + +```csharp +SentrySdk.Metrics.EmitCounter("button_click", 5, + new Dictionary { ["browser"] = "Firefox" }); +SentrySdk.Metrics.EmitGauge("page_load", 15.0, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["page"] = "/home" }); +SentrySdk.Metrics.EmitDistribution("api_latency", 187, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["endpoint"] = "/api/orders" }); +``` + +## Verify Your Setup + +Let's test your setup and confirm that data reaches your Sentry project. +### View Captured Data in Sentry + +Open your Sentry project to view the captured event. + ## Next Steps +At this point, you should have integrated Sentry into your .NET for Android application. Here's what to explore next: + - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Learn how to [manually capture errors](/platforms/dotnet/usage/) +- Explore [Tracing](/platforms/dotnet/tracing/) +- Configure the embedded Android SDK with Android Native Options diff --git a/docs/platforms/dotnet/guides/apple/index.mdx b/docs/platforms/dotnet/guides/apple/index.mdx index 1e22ffc0d3b261..cacafbc17d0c4c 100644 --- a/docs/platforms/dotnet/guides/apple/index.mdx +++ b/docs/platforms/dotnet/guides/apple/index.mdx @@ -6,17 +6,6 @@ description: "Learn about Sentry's .NET integration with .NET for iOS, macOS, an Sentry supports [.NET for iOS, macOS, and Mac Catalyst](https://learn.microsoft.com/dotnet/ios/) directly from the [Sentry NuGet package](https://www.nuget.org/packages/Sentry). -## Overview of the features - -- All the features of our main [.NET SDK](/platforms/dotnet/), for your managed code -- Native crash reporting for Apple platforms, leveraging our [Cocoa SDK](/platforms/apple/) including: - - Automatically [attach screenshots to Native exceptions](/platforms/apple/guides/ios/configuration/options/#attach-screenshot) - - Detect [App Hangs](/platforms/apple/configuration/app-hangs/) - - [Automatic performance tracing](/platforms/apple/performance/) - - [Automatic breadcrumbs](/platforms/apple/enriching-events/breadcrumbs/#automatic-breadcrumbs) - - [Swizzling](/platforms/apple/configuration/swizzling/) -- Automatic session tracking and [release health](/product/releases/) - ## Install Add the Sentry dependency to your .NET for iOS, macOS, and/or Mac Catalyst application: @@ -31,8 +20,30 @@ Install-Package Sentry -Version {{@inject packages.version('sentry.dotnet') }} ## Configure +**Error Monitoring** starts working as soon as you call `SentrySdk.Init()`. **Logs** sent through `SentrySdk.Logger` and **Application Metrics** need no extra configuration. You'll learn how to send them in [Send Logs](#send-logs) and [Send Application Metrics](#send-application-metrics-). + +This guide also enables **Tracing**, **Profiling**, and **Session Replay** (experimental). + +On .NET for iOS, macOS, and Mac Catalyst, you also get: + +- All the features of our main [.NET SDK](/platforms/dotnet/), for your managed code +- Native crash reporting for Apple platforms, leveraging our [Cocoa SDK](/platforms/apple/) including: + - Automatically [attach screenshots to Native exceptions](/platforms/apple/guides/ios/configuration/options/#attachScreenshot) + - Detect [App Hangs](/platforms/apple/configuration/app-hangs/) + - [Automatic performance tracing](/platforms/apple/tracing/) + - [Automatic breadcrumbs](/platforms/apple/enriching-events/breadcrumbs/#automatic-breadcrumbs) + - [Swizzling](/platforms/apple/configuration/swizzling/) +- Automatic session tracking and [release health](/product/releases/) + In your `AppDelegate.cs` file, call `SentrySdk.Init` in the `FinishedLaunching` event and include any options you would like to set. The `Dsn` is the only required parameter. +The snippet also turns on: + +- Tracing: via `TracesSampleRate` +- Profiling: via `ProfilesSampleRate`. On iOS and Mac Catalyst, the SDK adds the native profiling integration automatically, so you don't need the `Sentry.Profiling` package. +- Session Replay: via `Native.ExperimentalOptions.SessionReplay` + +Don't need a feature? Remove its options from the snippet. ```csharp [Register("AppDelegate")] @@ -45,6 +56,13 @@ public class AppDelegate : UIApplicationDelegate { options.Dsn = "___PUBLIC_DSN___"; options.SendDefaultPii = true; // adds the user's IP address automatically + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. + options.TracesSampleRate = 1.0; + // Enables Profiling. + // Set to 1.0 to profile 100% of captured transactions. + options.ProfilesSampleRate = 1.0; #if DEBUG // Log debug information about the Sentry SDK options.Debug = true; @@ -57,6 +75,10 @@ public class AppDelegate : UIApplicationDelegate // https://docs.sentry.io/platforms/apple/guides/ios/configuration/options/#attachScreenshot options.Native.AttachScreenshot = true; + // Session Replay is currently available via the ExperimentalOptions + options.Native.ExperimentalOptions.SessionReplay.OnErrorSampleRate = 1.0; + options.Native.ExperimentalOptions.SessionReplay.SessionSampleRate = 1.0; + options.SetBeforeSend(evt => { if (evt.Exception?.Message.Contains("Something you don't care want logged?") ?? false) @@ -73,6 +95,8 @@ public class AppDelegate : UIApplicationDelegate Console.WriteLine(e); }; }); + + return true; } } ``` @@ -85,12 +109,47 @@ The .NET for iOS, macOS, and Mac Catalyst integration is part of [Sentry](/platf For configuration of the embedded Sentry Cocoa SDK, see Apple Native Options. -## Verify +## Send Logs + +Use `SentrySdk.Logger` to send logs at different levels. These logs are sent without an additional option. + +See Set Up Logs for all available logging methods and formatting options. + +```csharp +SentrySdk.Logger.LogInfo("Order processed"); +SentrySdk.Logger.LogWarning("Rate limit reached for /api/orders"); +``` + +## Send Application Metrics -This snippet includes an intentional error, so you can test that everything is working as soon as you set it up. +Metrics are enabled by default in Sentry .NET SDK 6.1.0 and later. Use `SentrySdk.Metrics` to send counters, gauges, and distributions from your app. + +See Set Up Metrics for all available metric types and configuration options. + +```csharp +SentrySdk.Metrics.EmitCounter("button_click", 5, + new Dictionary { ["browser"] = "Firefox" }); +SentrySdk.Metrics.EmitGauge("page_load", 15.0, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["page"] = "/home" }); +SentrySdk.Metrics.EmitDistribution("api_latency", 187, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["endpoint"] = "/api/orders" }); +``` + +## Verify Your Setup + +Let's test your setup and confirm that data reaches your Sentry project. +### View Captured Data in Sentry + +Open your Sentry project to view the captured event. + ## Next Steps +At this point, you should have integrated Sentry into your .NET for iOS, macOS, or Mac Catalyst application. Here's what to explore next: + - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Learn how to [manually capture errors](/platforms/dotnet/usage/) +- Explore [Tracing](/platforms/dotnet/tracing/) +- Configure the embedded Cocoa SDK with Apple Native Options diff --git a/docs/platforms/dotnet/guides/aspnet/index.mdx b/docs/platforms/dotnet/guides/aspnet/index.mdx index 0f9f035ef343f1..a49d3a19ad296f 100644 --- a/docs/platforms/dotnet/guides/aspnet/index.mdx +++ b/docs/platforms/dotnet/guides/aspnet/index.mdx @@ -6,16 +6,7 @@ description: "Learn about Sentry's .NET integration with ASP.NET." Sentry provides an integration with ASP.NET through the [Sentry.AspNet NuGet package](https://www.nuget.org/packages/Sentry.AspNet). -## Features - -In addition to capturing errors, you can monitor interactions between multiple services or applications by [enabling tracing](/concepts/key-terms/tracing/). - -Select which Sentry features you'd like to install in addition to Error Monitoring to get the corresponding installation and configuration instructions below. - ## Install - - - Add the Sentry dependency: ```powershell {tabTitle:Package Manager} @@ -31,9 +22,21 @@ as well as your logs as breadcrumbs. The logging integrations also capture event ## Configure +**Error Monitoring** starts working as soon as you initialize the SDK. **Logs** sent through `SentrySdk.Logger` and **Application Metrics** need no extra configuration. You'll learn how to send them in [Send Logs](#send-logs) and [Send Application Metrics](#send-application-metrics-). + +This guide also enables **Tracing**. + + You configure the SDK in the `Global.asax.cs`: +The snippet also turns on: + +- Tracing: via `TracesSampleRate` +- Logs from logging integrations: via `EnableLogs` + +Don't need a feature? Remove its options from the snippet. + ```csharp using System; using System.Web; @@ -55,12 +58,11 @@ public class MvcApplication : HttpApplication options.Debug = true; // Adds request URL and headers, IP and name for users, etc. options.SendDefaultPii = true; - - // ___PRODUCT_OPTION_START___ performance - // Set traces_sample_rate to 1.0 to capture 100% of transactions for performance monitoring. - // We recommend adjusting this value in production. + options.EnableLogs = true; + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. options.TracesSampleRate = 1.0; - // ___PRODUCT_OPTION_END___ performance // If you also installed the Sentry.EntityFramework package options.AddEntityFramework(); @@ -70,8 +72,6 @@ public class MvcApplication : HttpApplication // Global error catcher protected void Application_Error() => Server.CaptureLastError(); - - // ___PRODUCT_OPTION_START___ performance protected void Application_BeginRequest() { Context.StartSentryTransaction(); @@ -81,7 +81,6 @@ public class MvcApplication : HttpApplication { Context.FinishSentryTransaction(); } - // ___PRODUCT_OPTION_END___ performance protected void Application_End() { @@ -116,12 +115,44 @@ Opt-in to send the request body to Sentry: options.AddAspNet(RequestSize.Always); ``` -## Verify +## Send Logs + +Use `SentrySdk.Logger` to send logs at different levels without an additional option. If you also send logs through an integration, set `EnableLogs = true` in the initialization snippet. + +If you use Serilog, NLog, or log4net, see the documented [Serilog](/platforms/dotnet/guides/serilog/), [NLog](/platforms/dotnet/guides/nlog/), and [log4net](/platforms/dotnet/guides/log4net/) integrations. -This snippet includes an intentional error, so you can test that everything is working as soon as you set it up. +See Set Up Logs for all available logging methods and formatting options. + +```csharp +SentrySdk.Logger.LogInfo("Order processed"); +SentrySdk.Logger.LogWarning("Rate limit reached for /api/orders"); +``` + +## Send Application Metrics + +Metrics are enabled by default in Sentry .NET SDK 6.1.0 and later. Use `SentrySdk.Metrics` to send counters, gauges, and distributions from your app. + +See Set Up Metrics for all available metric types and configuration options. + +```csharp +SentrySdk.Metrics.EmitCounter("button_click", 5, + new Dictionary { ["browser"] = "Firefox" }); +SentrySdk.Metrics.EmitGauge("page_load", 15.0, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["page"] = "/home" }); +SentrySdk.Metrics.EmitDistribution("api_latency", 187, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["endpoint"] = "/api/orders" }); +``` + +## Verify Your Setup + +Let's test your setup and confirm that data reaches your Sentry project. +### View Captured Data in Sentry + +Open your Sentry project to view the captured event. + ## Troubleshooting For information about Troubleshooting, please visit the [troubleshooting](troubleshooting/) page. @@ -132,4 +163,8 @@ For information about Troubleshooting, please visit the [troubleshooting](troubl ## Next Steps +At this point, you should have integrated Sentry into your ASP.NET application. Here's what to explore next: + - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Learn how to [manually capture errors](/platforms/dotnet/usage/) +- Explore [Tracing](/platforms/dotnet/tracing/) diff --git a/docs/platforms/dotnet/guides/aspnetcore/index.mdx b/docs/platforms/dotnet/guides/aspnetcore/index.mdx index 16fe5517e55882..4b33240722ecea 100644 --- a/docs/platforms/dotnet/guides/aspnetcore/index.mdx +++ b/docs/platforms/dotnet/guides/aspnetcore/index.mdx @@ -6,16 +6,7 @@ description: "Learn about Sentry's .NET integration with ASP.NET Core." Sentry provides an integration with ASP.NET Core through the [Sentry.AspNetCore](https://www.nuget.org/packages/Sentry.AspNetCore) NuGet package. -## Features - -In addition to capturing errors, you can monitor interactions between multiple services or applications by [enabling tracing](/concepts/key-terms/tracing/). - -Select which Sentry features you'd like to install in addition to Error Monitoring to get the corresponding installation and configuration instructions below. - ## Install - - - Add the Sentry dependency: ```powershell {tabTitle:Package Manager} @@ -32,15 +23,34 @@ paket add Sentry --version {{@inject packages.version('sentry.dotnet.aspnetcore' This package extends [Sentry.Extensions.Logging](/platforms/dotnet/guides/extensions-logging/). This means that besides the ASP.NET Core related features, through this package you'll also get access to all the framework's logging integration and also the features available in the main [Sentry](/platforms/dotnet/) SDK. -## Initialize +## Configure + +**Error Monitoring** starts working as soon as you initialize the SDK. **Logs** sent through `Microsoft.Extensions.Logging` need `EnableLogs = true`, and **Application Metrics** need no extra configuration. You'll learn how to send them in [Send Logs](#send-logs) and [Send Application Metrics](#send-application-metrics-). + +This guide also enables **Tracing**. The simplest way to initialize Sentry in ASP.NET Core is by using the `UseSentry` extension method from the `Sentry.AspNetCore` package in conjunction with the [framework configuration system](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-7.0). -When configuring the SDK via the frameworks configuration system, it's possible to add the SDK by simply calling `UseSentry` without providing any further information. The SDK provides this as extension methods to support ASP.NET Core `2.X`, `3.X`, and `5.X` and later: +Call `UseSentry` with your DSN and the options you want. The SDK provides this as extension methods to support ASP.NET Core `2.X`, `3.X`, and `5.X` and later. + +The snippet also turns on: + +- Tracing: via `TracesSampleRate` +- Logs: via `EnableLogs` + +Don't need a feature? Remove its options from the snippet. ```csharp {tabTitle:WebApplication} {mdExpandTabs} var builder = WebApplication.CreateBuilder(args); -builder.WebHost.UseSentry(); // Initialize Sentry +builder.WebHost.UseSentry(options => +{ + options.Dsn = "___PUBLIC_DSN___"; + options.EnableLogs = true; + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. + options.TracesSampleRate = 1.0; +}); ``` ```csharp {tabTitle:IHostBuilder} @@ -48,19 +58,33 @@ public static IHostBuilder CreateHostBuilder(string[] args) => Host.CreateDefaultBuilder(args) .ConfigureWebHostDefaults(webBuilder => { - // Add the following line: - webBuilder.UseSentry(); + webBuilder.UseSentry(options => + { + options.Dsn = "___PUBLIC_DSN___"; + options.EnableLogs = true; + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. + options.TracesSampleRate = 1.0; + }); }); ``` ```csharp {tabTitle:IWebHost} public static IWebHost BuildWebHost(string[] args) => WebHost.CreateDefaultBuilder(args) - // Add the following line: - .UseSentry() + .UseSentry(options => + { + options.Dsn = "___PUBLIC_DSN___"; + options.EnableLogs = true; + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. + options.TracesSampleRate = 1.0; + }) ``` -## Configure +### Additional configuration The framework takes configuration settings from `appsettings.json`, environment variables, or from code. These settings get applied to `Sentry.AspNetCore.SentryAspNetCoreOptions`, which extends `Sentry.Extensions.Logging.SentryLoggingOptions`, which in turn extends `Sentry.SentryOptions`. This means options for `Sentry.AspNetCore` as well as all the inner packages are available to be configured through the configuration system. @@ -70,6 +94,7 @@ An example of some of the options that can be configured via `appsettings.json`: ```json {filename:appsettings.json} +{ "Sentry": { "Dsn": "___PUBLIC_DSN___", "SendDefaultPii": true, @@ -78,19 +103,11 @@ An example of some of the options that can be configured via `appsettings.json`: "MinimumEventLevel": "Warning", "AttachStackTrace": true, "Debug": true, - "DiagnosticLevel": "Error", - // ___PRODUCT_OPTION_START___ performance - "TracesSampleRate": 1.0 - // ___PRODUCT_OPTION_END___ performance - }, + "DiagnosticLevel": "Error" + } +} ``` - - -Setting `TracesSampleRate` to `1.0` in this example configures Sentry to capture 100% of transactions for tracing. We recommend adjusting this value in production. See Automatic Instrumentation for further information. - - - ### Environment variables It's also possible to bind properties to the SDK via environment variables, like: @@ -113,9 +130,10 @@ Finally, any settings that can be configured via `appsettings.json` or environme .UseSentry(options => { options.SendDefaultPii = true; // Adds request URL and headers, IP and name for users, etc. - // ___PRODUCT_OPTION_START___ performance - options.TracesSampleRate = 1.0; // Set this to configure automatic tracing - // ___PRODUCT_OPTION_END___ performance + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. + options.TracesSampleRate = 1.0; options.SetBeforeSend((@event, hint) => { // Never report server names @@ -128,9 +146,10 @@ Finally, any settings that can be configured via `appsettings.json` or environme ```fsharp .UseSentry (fun options -> options.SendDefaultPii <- true // Adds request URL and headers, IP and name for users, etc. - // ___PRODUCT_OPTION_START___ performance - options.TracesSampleRate <- 1.0 // Set this to configure automatic tracing - // ___PRODUCT_OPTION_END___ performance + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. + options.TracesSampleRate <- 1.0 options.SetBeforeSend(fun event hint -> // Never report server names event.ServerName <- null @@ -141,21 +160,15 @@ Finally, any settings that can be configured via `appsettings.json` or environme > Example modifying all events before they are sent to avoid server names being reported. -## Verify - -This snippet includes an intentional error, so you can test that everything is working as soon as you set it up. - - - -## Dependency Injection +### Dependency Injection Much of the behavior of the ASP.NET Core integration with Sentry can be customized by using the frameworks dependency injection system. That is done by registering your own implementation of some of the exposed abstraction. -### Lifetimes +#### Lifetimes The lifetime used will be respected by the SDK. For example, when registering a `Transient` dependency, a new instance of the processor is created for each event sent out to Sentry. This allows the use of non thread-safe event processors. -### Capturing the affected user +#### Capturing the affected user When opting-in to [SendDefaultPii](#senddefaultpii), the SDK will automatically read the user from the request by inspecting `HttpContext.User`. Default claim values like `NameIdentifier` for the _Id_ will be used. @@ -173,7 +186,7 @@ member this.ConfigureServices(services: IServiceCollection) = services.AddSingleton() |> ignore ``` -### Adding event and exception processors +#### Adding event and exception processors Event processors and exception processors can be added via DI: @@ -191,17 +204,17 @@ member this.ConfigureServices(services: IServiceCollection) = services.AddScoped() |> ignore ``` -## Options and Initialization +### Options and Initialization As previously mentioned, this package is a wrapper around [Sentry.Extensions.Logging](/platforms/dotnet/guides/extensions-logging/) and [Sentry](/platforms/dotnet/). Please refer to the documentation of these packages to get the options that are defined at those levels. Below, the options that are specific to `Sentry.AspNetCore` will be described. -### SendDefaultPii +#### SendDefaultPii Although this setting is part of the [Sentry](/platforms/dotnet/) package, in the context of ASP.NET Core, it means reporting the user by reading the frameworks `HttpContext.User`. The strategy to create the `SentryUser` can be customized. Please read [retrieving user info](#capturing-the-affected-user) for more. -### Environment +#### Environment The environment name is automatically populated by reading the frameworks `IHostingEnvironment` value. @@ -213,7 +226,7 @@ Methods that take precedence over `IHostingEnvironment` are: - Environment variable _SENTRY_ENVIRONMENT_ - Configuration system like `appsettings.json` -### MaxRequestBodySize +#### MaxRequestBodySize This parameter controls whether integrations should capture HTTP request bodies. It can be set to one of the following values: @@ -224,7 +237,7 @@ This parameter controls whether integrations should capture HTTP request bodies. If the request bodies should be captured, all requests will have the `EnableRewind` method invoked. This is done so that the request data can be read later, in case an error happens while processing the request. -### CaptureBlockingCalls +#### CaptureBlockingCalls When set to `true`, the SDK will detect blocking calls in async methods (like `Task.Wait()` and `Task.Result`) and report these to Sentry as errors. Blocking calls can lead to [Threadpool starvation](https://learn.microsoft.com/en-nz/archive/blogs/vancem/diagnosing-net-core-threadpool-starvation-with-perfview-why-my-service-is-not-saturating-all-cores-or-seems-to-stall). @@ -240,24 +253,18 @@ This feature makes use of the `Ben.BlockingDetector` library and so has [the sam > > It will detect CLR-initiated waits lock, `ManualResetEventSlim`, `Semaphore\{Slim\}`, `Task.Wait`, `Task.Result` etc. if they do block. -### IncludeActivityData +#### IncludeActivityData Opt-in to capture values from [System.Diagnostic.Activity](https://github.com/dotnet/runtime/blob/master/src/libraries/System.Diagnostics.DiagnosticSource/src/ActivityUserGuide.md) if one exists. -## Samples - -- A [simple example](https://github.com/getsentry/sentry-dotnet/tree/main/samples/Sentry.Samples.AspNetCore.Basic) without MVC. (**C#**) -- An [example](https://github.com/getsentry/sentry-dotnet/tree/main/samples/Sentry.Samples.AspNetCore.Mvc) using MVC and most of the SDK features. (**C#**) -- An [example](https://github.com/sentry-demos/giraffe) using Giraffe on top of ASP.NET Core with a basic overview of available features. (**F#**) -- For [more samples](https://github.com/getsentry/sentry-dotnet-samples) of the .NET SDKs. -## Tunnel +### Tunnel If events are being logged to Sentry from the client-side, then you should use a [tunnel](/platforms/javascript/troubleshooting/#using-the-tunnel-option). A tunnel is an HTTP endpoint that acts as a proxy between Sentry and your application. Because you control this server, there is no risk of any requests sent to it being blocked. -### Usage +#### Usage - Add to the container by calling `AddSentryTunneling();` on `IServiceCollection`. - Add the web app by calling `UseSentryTunneling();` on `IApplicationBuilder`. @@ -274,6 +281,68 @@ Sentry.init({ The [AspNetCore.Mvc sample](https://github.com/getsentry/sentry-dotnet/tree/main/samples/Sentry.Samples.AspNetCore.Mvc) uses this approach. + +## Send Logs + +Use `Microsoft.Extensions.Logging` to send structured logs from your application. Set `EnableLogs = true` in your Sentry initialization. + +See [Microsoft.Extensions.Logging](/platforms/dotnet/guides/extensions-logging/) for setup details. + +See Set Up Logs for all available logging methods and formatting options. + +```csharp +using Microsoft.Extensions.Logging; + +public sealed class OrderService +{ + private readonly ILogger _logger; + + public OrderService(ILogger logger) => _logger = logger; + + public void Process() + { + _logger.LogInformation("Order processed {OrderId}", "order-123"); + _logger.LogWarning("Rate limit reached for {Endpoint}", "/api/orders"); + } +} +``` + +## Send Application Metrics + +Metrics are enabled by default in Sentry .NET SDK 6.1.0 and later. Use `SentrySdk.Metrics` to send counters, gauges, and distributions from your app. + +See Set Up Metrics for all available metric types and configuration options. + +```csharp +SentrySdk.Metrics.EmitCounter("button_click", 5, + new Dictionary { ["browser"] = "Firefox" }); +SentrySdk.Metrics.EmitGauge("page_load", 15.0, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["page"] = "/home" }); +SentrySdk.Metrics.EmitDistribution("api_latency", 187, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["endpoint"] = "/api/orders" }); +``` + +## Verify Your Setup + +Let's test your setup and confirm that data reaches your Sentry project. + + + +### View Captured Data in Sentry + +Open your Sentry project to view the captured event. + +## Samples + +- A [simple example](https://github.com/getsentry/sentry-dotnet/tree/main/samples/Sentry.Samples.AspNetCore.Basic) without MVC. (**C#**) +- An [example](https://github.com/getsentry/sentry-dotnet/tree/main/samples/Sentry.Samples.AspNetCore.Mvc) using MVC and most of the SDK features. (**C#**) +- An [example](https://github.com/sentry-demos/giraffe) using Giraffe on top of ASP.NET Core with a basic overview of available features. (**F#**) +- For [more samples](https://github.com/getsentry/sentry-dotnet-samples) of the .NET SDKs. + ## Next Steps +At this point, you should have integrated Sentry into your ASP.NET Core application. Here's what to explore next: + - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Learn how to [manually capture errors](/platforms/dotnet/usage/) +- Explore [Tracing](/platforms/dotnet/tracing/) diff --git a/docs/platforms/dotnet/guides/aws-lambda/index.mdx b/docs/platforms/dotnet/guides/aws-lambda/index.mdx index 4111c1f1a8b09e..088b899271e1fa 100644 --- a/docs/platforms/dotnet/guides/aws-lambda/index.mdx +++ b/docs/platforms/dotnet/guides/aws-lambda/index.mdx @@ -6,16 +6,7 @@ description: "Learn about Sentry's .NET integration with AWS Lambda and ASP.NET Sentry provides an integration with AWS Lambda ASP.NET Core Server through the [Sentry.AspNetCore NuGet package](https://www.nuget.org/packages/Sentry.AspNetCore). -## Features - -In addition to capturing errors, you can monitor interactions between multiple services or applications by [enabling tracing](/concepts/key-terms/tracing/). - -Select which Sentry features you'd like to install in addition to Error Monitoring to get the corresponding installation and configuration instructions below. - ## Install - - - Add the Sentry dependency: ```powershell {tabTitle:Package Manager} @@ -30,11 +21,23 @@ You can combine this integration with a logging library like `log4net`, `NLog`, ## Configure +**Error Monitoring** starts working as soon as you initialize the SDK. **Logs** sent through `Microsoft.Extensions.Logging` need `EnableLogs = true`, and **Application Metrics** need no extra configuration. You'll learn how to send them in [Send Logs](#send-logs) and [Send Application Metrics](#send-application-metrics-). + +This guide also enables **Tracing**. + + All `ASP.NET Core` configurations are valid here. But one configuration in particular is relevant. `FlushOnCompletedRequest` ensures all events are flushed out. This is because the general ASP.NET Core hooks for when the process is exiting are not guaranteed to run in a serverless environment. This setting ensures that no event is lost if AWS recycles the process. +The snippet also turns on: + +- Tracing: via `TracesSampleRate` +- Logs: via `EnableLogs` + +Don't need a feature? Remove its options from the snippet. + ```csharp public class LambdaEntryPoint : Amazon.Lambda.AspNetCoreServer.APIGatewayProxyFunction { @@ -45,16 +48,15 @@ public class LambdaEntryPoint : Amazon.Lambda.AspNetCoreServer.APIGatewayProxyFu .UseSentry(options => { options.Dsn = "___PUBLIC_DSN___"; + options.EnableLogs = true; // When configuring for the first time, to see what the SDK is doing: - o.Debug = true; + options.Debug = true; // Adds request URL and headers, IP and name for users, etc. - o.SendDefaultPii = true; - // ___PRODUCT_OPTION_START___ performance - // Set TracesSampleRate to 1.0 to capture 100% - // of transactions for tracing. - // We recommend adjusting this value in production - o.TracesSampleRate = 1.0; - // ___PRODUCT_OPTION_END___ performance + options.SendDefaultPii = true; + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. + options.TracesSampleRate = 1.0; // Required in Serverless environments options.FlushOnCompletedRequest = true; }) @@ -65,16 +67,64 @@ public class LambdaEntryPoint : Amazon.Lambda.AspNetCoreServer.APIGatewayProxyFu Check out the [Sentry ASP.NET Core](/platforms/dotnet/guides/aspnetcore/) documentation for the complete set of options. -## Verify +## Send Logs + +Use `Microsoft.Extensions.Logging` to send structured logs from your application. Set `EnableLogs = true` in your Sentry initialization. + +See [Microsoft.Extensions.Logging](/platforms/dotnet/guides/extensions-logging/) for setup details. + +See Set Up Logs for all available logging methods and formatting options. + +```csharp +using Microsoft.Extensions.Logging; + +public sealed class OrderService +{ + private readonly ILogger _logger; + + public OrderService(ILogger logger) => _logger = logger; + + public void Process() + { + _logger.LogInformation("Order processed {OrderId}", "order-123"); + _logger.LogWarning("Rate limit reached for {Endpoint}", "/api/orders"); + } +} +``` + +## Send Application Metrics + +Metrics are enabled by default in Sentry .NET SDK 6.1.0 and later. Use `SentrySdk.Metrics` to send counters, gauges, and distributions from your app. -This snippet includes an intentional error, so you can test that everything is working as soon as you set it up. +See Set Up Metrics for all available metric types and configuration options. + +```csharp +SentrySdk.Metrics.EmitCounter("button_click", 5, + new Dictionary { ["browser"] = "Firefox" }); +SentrySdk.Metrics.EmitGauge("page_load", 15.0, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["page"] = "/home" }); +SentrySdk.Metrics.EmitDistribution("api_latency", 187, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["endpoint"] = "/api/orders" }); +``` + +## Verify Your Setup + +Let's test your setup and confirm that data reaches your Sentry project. +### View Captured Data in Sentry + +Open your Sentry project to view the captured event. + ## Samples - Our [samples on GitHub](https://github.com/getsentry/sentry-dotnet/tree/main/samples/Sentry.Samples.Aws.Lambda.AspNetCoreServer) demonstrate Sentry on AWS Lambda. (**C#**) ## Next Steps +At this point, you should have integrated Sentry into your AWS Lambda application. Here's what to explore next: + - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Learn how to [manually capture errors](/platforms/dotnet/usage/) +- Explore [Tracing](/platforms/dotnet/tracing/) diff --git a/docs/platforms/dotnet/guides/azure-functions-worker/index.mdx b/docs/platforms/dotnet/guides/azure-functions-worker/index.mdx index a26ea50fc8845f..7fa4beee87e095 100644 --- a/docs/platforms/dotnet/guides/azure-functions-worker/index.mdx +++ b/docs/platforms/dotnet/guides/azure-functions-worker/index.mdx @@ -6,60 +6,47 @@ description: "Learn about Sentry's .NET integration with Azure Functions." Sentry provides an integration with Azure Functions through the [Sentry.Extensions.Logging](https://www.nuget.org/packages/Sentry.Extensions.Logging) and [Sentry.OpenTelemetry.Exporter](https://www.nuget.org/packages/Sentry.OpenTelemetry.Exporter) NuGet packages. -## Features - -In addition to capturing errors, you can monitor interactions between multiple services or applications by enabling tracing. - -Select which Sentry features you'd like to install in addition to Error Monitoring to get the corresponding installation and configuration instructions below. - ## Install - - Add the Sentry dependencies to your Azure Functions application: ```shell {tabTitle:.NET Core CLI} dotnet add package Sentry.Extensions.Logging -v {{@inject packages.version('sentry.dotnet.extensions.logging') }} -// ___PRODUCT_OPTION_START___ performance dotnet add package Sentry.OpenTelemetry.Exporter -v {{@inject packages.version('sentry.dotnet') }} dotnet add package OpenTelemetry.Extensions.Hosting dotnet add package OpenTelemetry.Instrumentation.Http - -// ___PRODUCT_OPTION_END___ ``` ```powershell {tabTitle:Package Manager} Install-Package Sentry.Extensions.Logging -Version {{@inject packages.version('sentry.dotnet.extensions.logging') }} -// ___PRODUCT_OPTION_START___ performance Install-Package Sentry.OpenTelemetry.Exporter -Version {{@inject packages.version('sentry.dotnet') }} Install-Package OpenTelemetry.Extensions.Hosting Install-Package OpenTelemetry.Instrumentation.Http -// ___PRODUCT_OPTION_END___ ``` The [Sentry.Extensions.Logging](/platforms/dotnet/guides/extensions-logging/) package also provides access to the `ILogger` integration and the other core features available in the [Sentry](/platforms/dotnet/) SDK. ## Configure -The core features of Sentry are enabled by calling `AddSentry` when configuring logging. +**Error Monitoring** starts working as soon as you initialize the SDK by calling `AddSentry` when configuring logging. **Logs** sent through `Microsoft.Extensions.Logging` need `EnableLogs = true`, and **Application Metrics** need no extra configuration. You'll learn how to send them in [Send Logs](#send-logs) and [Send Application Metrics](#send-application-metrics-). + +This guide also enables **Tracing** through OpenTelemetry. Sentry's OTLP exporter is added to the OpenTelemetry `TracerProviderBuilder`, and `UseOtlp()` tells the Sentry SDK to use OpenTelemetry for tracing. - -To enable tracing, add Sentry's OTLP exporter to the OpenTelemetry `TracerProviderBuilder` and call `UseOtlp()` on the Sentry options. See OpenTelemetry (OTLP) for sampling and trace propagation. - +The snippet also turns on: -For example: +- Tracing: via `AddSentryOtlpExporter` and `UseOtlp()`. Don't also set `TracesSampleRate`; OpenTelemetry handles tracing. See OpenTelemetry (OTLP) for sampling and trace propagation. +- Logs: via `EnableLogs` + +Don't need a feature? Remove its options from the snippet. ```csharp +using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Hosting; using Microsoft.Extensions.Logging; -// ___PRODUCT_OPTION_START___ performance -using Microsoft.Extensions.DependencyInjection; using OpenTelemetry.Trace; -// ___PRODUCT_OPTION_END___ var host = new HostBuilder() .ConfigureFunctionsWorkerDefaults() -// ___PRODUCT_OPTION_START___ performance .ConfigureServices(services => { services.AddOpenTelemetry().WithTracing(builder => @@ -69,15 +56,13 @@ var host = new HostBuilder() .AddHttpClientInstrumentation(); // From OpenTelemetry.Instrumentation.Http, instruments outgoing HTTP requests }); }) -// ___PRODUCT_OPTION_END___ .ConfigureLogging(logging => { logging.AddSentry(options => { options.Dsn = "___PUBLIC_DSN___"; - // ___PRODUCT_OPTION_START___ performance + options.EnableLogs = true; options.UseOtlp(); // <-- Configure Sentry to use OpenTelemetry for tracing - // ___PRODUCT_OPTION_END___ options.Debug = true; }); }) @@ -86,16 +71,64 @@ var host = new HostBuilder() await host.RunAsync(); ``` -## Verify +## Send Logs + +Use `Microsoft.Extensions.Logging` to send structured logs from your application. Set `EnableLogs = true` in your Sentry initialization. + +See [Microsoft.Extensions.Logging](/platforms/dotnet/guides/extensions-logging/) for setup details. + +See Set Up Logs for all available logging methods and formatting options. + +```csharp +using Microsoft.Extensions.Logging; + +public sealed class OrderService +{ + private readonly ILogger _logger; + + public OrderService(ILogger logger) => _logger = logger; + + public void Process() + { + _logger.LogInformation("Order processed {OrderId}", "order-123"); + _logger.LogWarning("Rate limit reached for {Endpoint}", "/api/orders"); + } +} +``` + +## Send Application Metrics -This snippet includes an intentional error, so you can test that everything is working as soon as you set it up. +Metrics are enabled by default in Sentry .NET SDK 6.1.0 and later. Use `SentrySdk.Metrics` to send counters, gauges, and distributions from your app. + +See Set Up Metrics for all available metric types and configuration options. + +```csharp +SentrySdk.Metrics.EmitCounter("button_click", 5, + new Dictionary { ["browser"] = "Firefox" }); +SentrySdk.Metrics.EmitGauge("page_load", 15.0, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["page"] = "/home" }); +SentrySdk.Metrics.EmitDistribution("api_latency", 187, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["endpoint"] = "/api/orders" }); +``` + +## Verify Your Setup + +Let's test your setup and confirm that data reaches your Sentry project. +### View Captured Data in Sentry + +Open your Sentry project to view the captured event. + ## Samples - [Azure Functions Sample](https://github.com/getsentry/sentry-dotnet/blob/main/samples/Sentry.Samples.OpenTelemetry.AzureFunctions/) demonstrates Sentry with Azure Functions Isolated Worker SDK. (**C#**) ## Next Steps +At this point, you should have integrated Sentry into your Azure Functions application. Here's what to explore next: + - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Learn how to [manually capture errors](/platforms/dotnet/usage/) +- Learn more about tracing with OpenTelemetry (OTLP) diff --git a/docs/platforms/dotnet/guides/blazor-server/index.mdx b/docs/platforms/dotnet/guides/blazor-server/index.mdx index d2442ee2f9c5e4..c05548bffc8138 100644 --- a/docs/platforms/dotnet/guides/blazor-server/index.mdx +++ b/docs/platforms/dotnet/guides/blazor-server/index.mdx @@ -7,9 +7,6 @@ description: "Learn about Sentry's .NET integration with Blazor Interactive Serv Blazor Interactive SSR (also known as Blazor Server) runs components on the server and streams UI updates to the browser over a SignalR connection (circuit). Sentry integrates with Blazor Interactive SSR through the [Sentry.AspNetCore NuGet package](https://www.nuget.org/packages/Sentry.AspNetCore), which captures unhandled exceptions and provides optional tracing via OpenTelemetry. ## Install - - - Add the Sentry dependency to your Blazor Server application: ```shell {tabTitle:.NET Core CLI} @@ -24,8 +21,19 @@ This package extends [Sentry.Extensions.Logging](/platforms/dotnet/guides/extens ## Configure +**Error Monitoring** starts working as soon as you initialize the SDK. **Logs** sent through `SentrySdk.Logger` and **Application Metrics** need no extra configuration. You'll learn how to send them in [Send Logs](#send-logs) and [Send Application Metrics](#send-application-metrics-). + +This guide also enables **Tracing**. + + Initialize Sentry by calling `UseSentry` on your `WebHostBuilder`: +The snippet also turns on: + +- Tracing: via `TracesSampleRate` + +Don't need a feature? Remove its options from the snippet. + ```csharp {filename:Program.cs} var builder = WebApplication.CreateBuilder(args); @@ -39,9 +47,10 @@ builder.WebHost.UseSentry(options => options.Debug = true; // Adds request URL and headers, IP and name for users, etc. options.SendDefaultPii = true; - // ___PRODUCT_OPTION_START___ performance + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. options.TracesSampleRate = 0.1; - // ___PRODUCT_OPTION_END___ performance }); var app = builder.Build(); @@ -56,17 +65,17 @@ app.MapFallbackToPage("/_Host"); app.Run(); ``` -## Limited Tracing on .NET 10 and Later +### Limited Tracing on .NET 10 and Later Tracing events in Blazor Server applications is challenging due to the socket based nature of communications. However, on .NET 10 and later, Blazor emits OpenTelemetry activities for circuit lifecycle events, component navigation, and UI interactions that can be used to provide some limited tracing. The [Sentry.Samples.AspNetCore.Blazor.Server](https://github.com/getsentry/sentry-dotnet/tree/main/samples/Sentry.Samples.AspNetCore.Blazor.Server) sample project gives an example of this. -### Install OpenTelemetry +#### Install OpenTelemetry See OpenTelemetry Support for installation and setup instructions. -### Configure OpenTelemetry +#### Configure OpenTelemetry Wire up Sentry as an OpenTelemetry exporter, subscribe to the Blazor activity sources, and register helper services for circuit and breadcrumb tracking: @@ -94,6 +103,9 @@ builder.WebHost.UseSentry(options => { options.Dsn = "___PUBLIC_DSN___"; options.UseOpenTelemetry(); + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. options.TracesSampleRate = 0.1; // Rewrites /_blazor SignalR transaction names to the actual Blazor route options.AddEventProcessor(new BlazorEventProcessor()); @@ -116,7 +128,7 @@ app.MapFallbackToPage("/_Host"); app.Run(); ``` -### Circuit Lifecycle Tracking Services +#### Circuit Lifecycle Tracking Services The `BlazorSentryIntegration`, `SentryCircuitHandler`, and `BlazorEventProcessor` services shown above are not part of the Sentry integration. You can copy them from the [Blazor Server sample](https://github.com/getsentry/sentry-dotnet/tree/main/samples/Sentry.Samples.AspNetCore.Blazor.Server/Services) into your application if they prove useful for your use case. @@ -128,16 +140,50 @@ They provide the following features: | `SentryCircuitHandler` | Hooks into circuit open/close events to track circuit lifetime and prevent memory leaks | | `BlazorEventProcessor` | Rewrites uninformative SignalR transaction names (e.g. `/_blazor`) to the actual Blazor route | -## Verify +## Send Logs + +Use `SentrySdk.Logger` to send logs at different levels. These logs are sent without an additional option. -This snippet includes an intentional error, so you can test that everything is working as soon as you set it up. +See Set Up Logs for all available logging methods and formatting options. + +```csharp +SentrySdk.Logger.LogInfo("Order processed"); +SentrySdk.Logger.LogWarning("Rate limit reached for /api/orders"); +``` + +## Send Application Metrics + +Metrics are enabled by default in Sentry .NET SDK 6.1.0 and later. Use `SentrySdk.Metrics` to send counters, gauges, and distributions from your app. + +See Set Up Metrics for all available metric types and configuration options. + +```csharp +SentrySdk.Metrics.EmitCounter("button_click", 5, + new Dictionary { ["browser"] = "Firefox" }); +SentrySdk.Metrics.EmitGauge("page_load", 15.0, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["page"] = "/home" }); +SentrySdk.Metrics.EmitDistribution("api_latency", 187, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["endpoint"] = "/api/orders" }); +``` + +## Verify Your Setup + +Let's test your setup and confirm that data reaches your Sentry project. +### View Captured Data in Sentry + +Open your Sentry project to view the captured event. + ## Samples - This [integration with Blazor Interactive SSR](https://github.com/getsentry/sentry-dotnet/tree/main/samples/Sentry.Samples.AspNetCore.Blazor.Server) sample demonstrates using Sentry with Blazor Server, including enhanced circuit tracking on .NET 10. (**C#**) ## Next Steps +At this point, you should have integrated Sentry into your Blazor Server application. Here's what to explore next: + - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Learn how to [manually capture errors](/platforms/dotnet/usage/) +- Explore [Tracing](/platforms/dotnet/tracing/) diff --git a/docs/platforms/dotnet/guides/blazor-webassembly/index.mdx b/docs/platforms/dotnet/guides/blazor-webassembly/index.mdx index 5b784b93f6c633..bafbb652e24b12 100644 --- a/docs/platforms/dotnet/guides/blazor-webassembly/index.mdx +++ b/docs/platforms/dotnet/guides/blazor-webassembly/index.mdx @@ -7,9 +7,6 @@ description: "Learn about Sentry's .NET integration with Blazor WebAssembly." Sentry provides an integration with Blazor WebAssembly through the [Sentry.AspNetCore.Blazor.WebAssembly NuGet package](https://www.nuget.org/packages/Sentry.AspNetCore.Blazor.WebAssembly). ## Install - - - Add the Sentry dependency to your Blazor WebAssembly application: ```shell {tabTitle:.NET Core CLI} @@ -24,10 +21,22 @@ This package extends [Sentry.Extensions.Logging](/platforms/dotnet/guides/extens ## Configure +**Error Monitoring** starts working as soon as you initialize the SDK. **Logs** sent through `Microsoft.Extensions.Logging` need `EnableLogs = true`, and **Application Metrics** need no extra configuration. You'll learn how to send them in [Send Logs](#send-logs) and [Send Application Metrics](#send-application-metrics-). + +This guide also enables **Tracing**. + + Sentry integration with Blazor WebAssembly is done by calling `.UseSentry()` and specifying the options, for example: +The snippet also turns on: + +- Tracing: via `TracesSampleRate` +- Logs: via `EnableLogs` + +Don't need a feature? Remove its options from the snippet. + ```csharp using Microsoft.AspNetCore.Components.WebAssembly.Hosting; using Microsoft.Extensions.Logging; @@ -36,13 +45,15 @@ var builder = WebAssemblyHostBuilder.CreateDefault(args); builder.UseSentry(options => { options.Dsn = "___PUBLIC_DSN___"; + options.EnableLogs = true; // When configuring for the first time, to see what the SDK is doing: options.Debug = true; // Adds request URL and headers, IP and name for users, etc. options.SendDefaultPii = true; - // ___PRODUCT_OPTION_START___ performance + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. options.TracesSampleRate = 0.1; - // ___PRODUCT_OPTION_END___ performance }); // Captures logError and higher as events @@ -51,16 +62,64 @@ builder.Logging.AddSentry(o => o.InitializeSdk = false); await builder.Build().RunAsync(); ``` -## Verify +## Send Logs -This snippet includes an intentional error, so you can test that everything is working as soon as you set it up. +Use `Microsoft.Extensions.Logging` to send structured logs from your application. Set `EnableLogs = true` in your Sentry initialization. + +See [Microsoft.Extensions.Logging](/platforms/dotnet/guides/extensions-logging/) for setup details. + +See Set Up Logs for all available logging methods and formatting options. + +```csharp +using Microsoft.Extensions.Logging; + +public sealed class OrderService +{ + private readonly ILogger _logger; + + public OrderService(ILogger logger) => _logger = logger; + + public void Process() + { + _logger.LogInformation("Order processed {OrderId}", "order-123"); + _logger.LogWarning("Rate limit reached for {Endpoint}", "/api/orders"); + } +} +``` + +## Send Application Metrics + +Metrics are enabled by default in Sentry .NET SDK 6.1.0 and later. Use `SentrySdk.Metrics` to send counters, gauges, and distributions from your app. + +See Set Up Metrics for all available metric types and configuration options. + +```csharp +SentrySdk.Metrics.EmitCounter("button_click", 5, + new Dictionary { ["browser"] = "Firefox" }); +SentrySdk.Metrics.EmitGauge("page_load", 15.0, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["page"] = "/home" }); +SentrySdk.Metrics.EmitDistribution("api_latency", 187, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["endpoint"] = "/api/orders" }); +``` + +## Verify Your Setup + +Let's test your setup and confirm that data reaches your Sentry project. +### View Captured Data in Sentry + +Open your Sentry project to view the captured event. + ## Samples - This [integration with Blazor WebAssembly](https://github.com/getsentry/sentry-dotnet/tree/main/samples/Sentry.Samples.AspNetCore.Blazor.Wasm) sample demonstrates using Sentry with Blazor WebAssembly. (**C#**) ## Next Steps +At this point, you should have integrated Sentry into your Blazor WebAssembly application. Here's what to explore next: + - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Learn how to [manually capture errors](/platforms/dotnet/usage/) +- Explore [Tracing](/platforms/dotnet/tracing/) diff --git a/docs/platforms/dotnet/guides/entityframework/index.mdx b/docs/platforms/dotnet/guides/entityframework/index.mdx index da865b9022cf0d..d08272d0a7fc56 100644 --- a/docs/platforms/dotnet/guides/entityframework/index.mdx +++ b/docs/platforms/dotnet/guides/entityframework/index.mdx @@ -9,23 +9,14 @@ Sentry provides an integration with `EntityFramework` through the of the [Sentry > Looking for `EntityFramework Core`? If you're targeting .NET Core 3.1 or newer, that's already built in to the main Sentry .NET SDK. It's also enabled by default for our ASP.NET or ASP.NET Core integrations, even for older targets. For other scenarios, you may need to add the `Sentry.DiagnosticSource` package and call `AddDiagnosticSourceIntegration`, [as described here](/platforms/dotnet/tracing/instrumentation/automatic-instrumentation/#diagnosticsource-integration). (The rest of this page describes our EF6 integration, not EFCore.) -## Overview of the features +**Overview of the features** - Queries as breadcrumbs - Validation errors All queries executed are added as breadcrumbs and are sent with any event which happens on the same [scope](enriching-events/scopes/). Besides that, validation errors are also included as `Extra`. -## Features - -In addition to capturing errors, you can monitor interactions between multiple services or applications by [enabling tracing](/concepts/key-terms/tracing/). - -Select which Sentry features you'd like to install in addition to Error Monitoring to get the corresponding installation and configuration instructions below. - ## Install - - - ```powershell {tabTitle:Package Manager} Install-Package Sentry.EntityFramework -Version {{@inject packages.version('sentry.dotnet.ef') }} ``` @@ -36,7 +27,12 @@ dotnet add package Sentry.EntityFramework -v {{@inject packages.version('sentry. This package extends `Sentry` main SDK. That means that besides the EF features, through this package you'll also get access to all API and features available in the main `Sentry` SDK. -## Configuration +## Configure + +**Error Monitoring** starts working as soon as you initialize the SDK. **Logs** sent through `SentrySdk.Logger` and **Application Metrics** need no extra configuration. You'll learn how to send them in [Send Logs](#send-logs) and [Send Application Metrics](#send-application-metrics-). + +This guide also enables **Tracing**. + Add the Entity Framework 6 support to your project in one step: @@ -46,6 +42,12 @@ Add the Entity Framework 6 support to your project in one step: For example, configuring an ASP.NET app with _global.asax_: +The snippet also turns on: + +- Tracing: via `TracesSampleRate` + +Don't need a feature? Remove its options from the snippet. + ```csharp {filename:global.asax} using System; using System.Configuration; @@ -63,11 +65,10 @@ public class MvcApplication : System.Web.HttpApplication options.Dsn = ConfigurationManager.AppSettings["SentryDsn"]; // Adds request URL and headers, IP and name for users, etc. options.SendDefaultPii = true; - // ___PRODUCT_OPTION_START___ performance - // Set traces_sample_rate to 1.0 to capture 100% of transactions for performance monitoring. - // We recommend adjusting this value in production. + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. options.TracesSampleRate = 1.0; - // ___PRODUCT_OPTION_END___ performance // Add the EntityFramework integration options.AddEntityFramework(); }); @@ -75,8 +76,6 @@ public class MvcApplication : System.Web.HttpApplication // Global error catcher protected void Application_Error() => Server.CaptureLastError(); - - // ___PRODUCT_OPTION_START___ performance protected void Application_BeginRequest() { Context.StartSentryTransaction(); @@ -86,8 +85,6 @@ public class MvcApplication : System.Web.HttpApplication { Context.FinishSentryTransaction(); } - - // ___PRODUCT_OPTION_END___ performance public override void Dispose() { _sentrySdk.Dispose(); @@ -96,12 +93,42 @@ public class MvcApplication : System.Web.HttpApplication } ``` -## Verify +## Send Logs -This snippet includes an intentional error, so you can test that everything is working as soon as you set it up. +Use `SentrySdk.Logger` to send logs at different levels. These logs are sent without an additional option. + +See Set Up Logs for all available logging methods and formatting options. + +```csharp +SentrySdk.Logger.LogInfo("Order processed"); +SentrySdk.Logger.LogWarning("Rate limit reached for /api/orders"); +``` + +## Send Application Metrics + +Metrics are enabled by default in Sentry .NET SDK 6.1.0 and later. Use `SentrySdk.Metrics` to send counters, gauges, and distributions from your app. + +See Set Up Metrics for all available metric types and configuration options. + +```csharp +SentrySdk.Metrics.EmitCounter("button_click", 5, + new Dictionary { ["browser"] = "Firefox" }); +SentrySdk.Metrics.EmitGauge("page_load", 15.0, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["page"] = "/home" }); +SentrySdk.Metrics.EmitDistribution("api_latency", 187, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["endpoint"] = "/api/orders" }); +``` + +## Verify Your Setup + +Let's test your setup and confirm that data reaches your Sentry project. +### View Captured Data in Sentry + +Open your Sentry project to view the captured event. + ## Sample Check out a complete working [sample](https://github.com/getsentry/sentry-dotnet-ef/tree/master/samples/Sentry.Samples.AspNet.Mvc) to see it in action. @@ -110,4 +137,8 @@ Check out a complete working [sample](https://github.com/getsentry/sentry-dotnet ## Next Steps +At this point, you should have integrated Sentry into your Entity Framework application. Here's what to explore next: + - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Learn how to [manually capture errors](/platforms/dotnet/usage/) +- Explore [Tracing](/platforms/dotnet/tracing/) diff --git a/docs/platforms/dotnet/guides/google-cloud-functions/index.mdx b/docs/platforms/dotnet/guides/google-cloud-functions/index.mdx index 31193f41c65ed5..9b0f8af3ffd38d 100644 --- a/docs/platforms/dotnet/guides/google-cloud-functions/index.mdx +++ b/docs/platforms/dotnet/guides/google-cloud-functions/index.mdx @@ -6,29 +6,6 @@ description: "Learn about Sentry's .NET integration with Google Cloud Functions. Sentry provides an integration with `Google Cloud Functions` through the [Sentry.Google.Cloud.Functions NuGet package](https://www.nuget.org/packages/sentry.google.cloud.functions). -## Overview of the Features - -- Easy Google Cloud Functions integration, single line: `[assembly: FunctionsStartup(typeof(SentryStartup))]` -- Captures unhandled exceptions in the middleware pipeline -- Captures exceptions handled by the framework `UseExceptionHandler` -- Captures process-wide unhandled exceptions (AppDomain) -- Captures `LogError` or `LogCritical` -- Any event sent will include relevant application log messages -- RequestId as tag -- URL as tag -- Environment is automatically set (IHostingEnvironment) -- Request payload can be captured if opt-in -- Support for EventProcessors registered with DI -- Support for ExceptionProcessors registered with DI -- Supports configuration system (bind to `SentryAspNetCoreOptions`) -- Server OS info sent -- Server Runtime info sent -- Request headers sent -- HTTP Proxy configuration -- Request body compressed -- Event flooding protection (429 retry-after and internal bound queue) -- Assembly Strong named - ## Install Add the Sentry dependency: @@ -59,13 +36,44 @@ Messages logged from assemblies with the name starting with `Sentry` will not ge ## Configure +**Error Monitoring** starts working as soon as you initialize the SDK. **Application Metrics** need no extra configuration. You'll learn how to send them in [Send Application Metrics](#send-application-metrics-). + +This guide also enables **Tracing**. + +The `Sentry.Google.Cloud.Functions` integration also gives you: + +- Easy Google Cloud Functions integration, single line: `[assembly: FunctionsStartup(typeof(SentryStartup))]` +- Captures unhandled exceptions in the middleware pipeline +- Captures exceptions handled by the framework `UseExceptionHandler` +- Captures process-wide unhandled exceptions (AppDomain) +- Captures `LogError` or `LogCritical` +- Any event sent will include relevant application log messages +- RequestId as tag +- URL as tag +- Environment is automatically set (IHostingEnvironment) +- Request payload can be captured if opt-in +- Support for EventProcessors registered with DI +- Support for ExceptionProcessors registered with DI +- Supports configuration system (bind to `SentryAspNetCoreOptions`) +- Server OS info sent +- Server Runtime info sent +- Request headers sent +- HTTP Proxy configuration +- Request body compressed +- Event flooding protection (429 retry-after and internal bound queue) +- Assembly Strong named + The simplest way to configure the `Sentry.Google.Cloud.Functions` package is by setting up your Sentry configuration into `appsettings.json` using the assembly method `FunctionsStartup` to include the type `SentryStartup`. -For example: +The snippet also turns on: + +- Tracing: via `TracesSampleRate` +Don't need a feature? Remove its options from the snippet. ```json {filename:appsettings.json} +{ "Sentry": { "Dsn": "___PUBLIC_DSN___", "MaxRequestBodySize": "Always", @@ -74,12 +82,16 @@ For example: "MinimumEventLevel": "Warning", "AttachStackTrace": true, "Debug": true, - "DiagnosticsLevel": "Error" + "DiagnosticLevel": "Error", + "TracesSampleRate": 1.0 } +} ``` > An example of some of the options that can be configured via `appsettings.json`. +Setting `TracesSampleRate` to `1.0` captures 100% of spans. We recommend reducing this value in production. + To load the configurations, you will need to use the assembly `[assembly: FunctionsStartup(typeof(SentryStartup))]`. After being initialized, the framework automatically loads `appsettings.json` and environment variables, binding to `SentryAspNetCoreOptions`. ```csharp {tabTitle:Function.cs} @@ -124,11 +136,11 @@ public class CustomOptions : FunctionsStartup > Example modifying all events before they are sent to avoid server names being reported. -## Dependency Injection +### Dependency Injection Much of the behavior of the Google cloud functions integration with Sentry can be customized by using the frameworks dependency injection system. That is done by registering your own implementation of some of the exposed abstraction inside of `FunctionsStartup`. -### Capturing the Affected User +#### Capturing the Affected User When opting in to `SendDefaultPii`, the SDK will automatically read the user from the request by inspecting `HttpContext.User`. Default claim values like `NameIdentifier` for the _Id_ will be used. @@ -152,21 +164,40 @@ public class UserFactoryStartup : FunctionsStartup } ``` -### Options & Initialization +### Options and Initialization As previously mentioned, this package is a wrapper around [Sentry.Extensions.Logging](/platforms/dotnet/guides/extensions-logging/), [Sentry.AspNetCore](/platforms/dotnet/guides/aspnetcore/) and [Sentry](/platforms/dotnet/). Please refer to the documentation of these packages to get the options that are defined at those levels. -## Verify +## Send Application Metrics -This snippet includes an intentional error, so you can test that everything is working as soon as you set it up. +Metrics are enabled by default in Sentry .NET SDK 6.1.0 and later. Use `SentrySdk.Metrics` to send counters, gauges, and distributions from your app. + +See Set Up Metrics for all available metric types and configuration options. + +```csharp +SentrySdk.Metrics.EmitCounter("button_click", 5, + new Dictionary { ["browser"] = "Firefox" }); +SentrySdk.Metrics.EmitGauge("page_load", 15.0, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["page"] = "/home" }); +SentrySdk.Metrics.EmitDistribution("api_latency", 187, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["endpoint"] = "/api/orders" }); +``` + +## Verify Your Setup + +Let's test your setup and confirm that data reaches your Sentry project. -## Samples +### View Captured Data in Sentry -- [Google Cloud Functions sample](https://github.com/getsentry/sentry-dotnet/tree/main/samples/Sentry.Samples.Google.Cloud.Functions) -- For [more samples](https://github.com/getsentry/sentry-dotnet-samples) of the .NET SDKs. +Open your Sentry project to view the captured event. ## Next Steps +At this point, you should have integrated Sentry into your Google Cloud Functions application. Here's what to explore next: + - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Learn how to [manually capture errors](/platforms/dotnet/usage/) +- Explore [Tracing](/platforms/dotnet/tracing/) +- Check out the [Google Cloud Functions sample](https://github.com/getsentry/sentry-dotnet/tree/main/samples/Sentry.Samples.Google.Cloud.Functions), or browse [more samples](https://github.com/getsentry/sentry-dotnet-samples) of the .NET SDKs diff --git a/docs/platforms/dotnet/guides/maui/index.mdx b/docs/platforms/dotnet/guides/maui/index.mdx index 1d707e3568b51d..1688daecfafc07 100644 --- a/docs/platforms/dotnet/guides/maui/index.mdx +++ b/docs/platforms/dotnet/guides/maui/index.mdx @@ -6,7 +6,7 @@ description: "Learn about Sentry's .NET integration with .NET Multi-platform App Sentry has an integration for the [.NET Multi-platform App UI (MAUI)](https://dotnet.microsoft.com/apps/maui) through the [Sentry.Maui NuGet package](https://www.nuget.org/packages/Sentry.Maui). -## Overview of the features +**Overview of the features** - Easy MAUI integration by calling `UseSentry` on your `MauiAppBuilder` - All the features of our main [.NET SDK](/platforms/dotnet/), for your managed code @@ -18,16 +18,7 @@ Sentry has an integration for the [.NET Multi-platform App UI (MAUI)](https://do - Detailed device and runtime information passed on every event - Automatic session tracking enabled, to support [release health](/product/releases/) -## Features - -In addition to capturing errors, you can monitor interactions between multiple services or applications by [enabling tracing](/concepts/key-terms/tracing/). - -Select which Sentry features you'd like to install in addition to Error Monitoring to get the corresponding installation and configuration instructions below. - ## Install - - - Add the Sentry dependency to your .NET MAUI application: ```shell {tabTitle:.NET Core CLI} @@ -42,9 +33,21 @@ This package extends [Sentry.Extensions.Logging](/platforms/dotnet/guides/extens ## Configure +**Error Monitoring** starts working as soon as you initialize the SDK. **Logs** sent through `Microsoft.Extensions.Logging` need `EnableLogs = true`, and **Application Metrics** need no extra configuration. You'll learn how to send them in [Send Logs](#send-logs) and [Send Application Metrics](#send-application-metrics-). + +This guide also enables **Tracing**. + + In your `MauiProgram.cs` file, call `UseSentry` on your `MauiAppBuilder`, and include any options you would like to set. The `Dsn` is the only required parameter. +The snippet also turns on: + +- Tracing: via `TracesSampleRate` +- Logs: via `EnableLogs` + +Don't need a feature? Remove its options from the snippet. + ```csharp public static MauiApp CreateMauiApp() { @@ -57,6 +60,7 @@ public static MauiApp CreateMauiApp() { // The DSN is the only required setting. options.Dsn = "___PUBLIC_DSN___"; + options.EnableLogs = true; // Use debug mode if you want to see what the SDK is doing. // Debug messages are written to stdout with Console.Writeline, @@ -66,15 +70,12 @@ public static MauiApp CreateMauiApp() // Adds request URL and headers, IP and name for users, etc. options.SendDefaultPii = true; - - // ___PRODUCT_OPTION_START___ performance - // Set TracesSampleRate to 1.0 to capture 100% of transactions for tracing. - // We recommend adjusting this value in production. + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. options.TracesSampleRate = 1.0; - // ___PRODUCT_OPTION_END___ performance // If your app doesn't have sensitive data, you can get screenshots on error events automatically - // https://docs.sentry.io/platforms/dotnet/guides/maui/configuration/options/#AttachScreenshot options.AttachScreenshot = true; // Other Sentry options can be set here. @@ -127,12 +128,60 @@ Use caution when enabling, as such values may contain personally identifiable in -## Verify +## Send Logs + +Use `Microsoft.Extensions.Logging` to send structured logs from your application. Set `EnableLogs = true` in your Sentry initialization. -This snippet includes an intentional error, so you can test that everything is working as soon as you set it up. +See [Microsoft.Extensions.Logging](/platforms/dotnet/guides/extensions-logging/) for setup details. + +See Set Up Logs for all available logging methods and formatting options. + +```csharp +using Microsoft.Extensions.Logging; + +public sealed class OrderService +{ + private readonly ILogger _logger; + + public OrderService(ILogger logger) => _logger = logger; + + public void Process() + { + _logger.LogInformation("Order processed {OrderId}", "order-123"); + _logger.LogWarning("Rate limit reached for {Endpoint}", "/api/orders"); + } +} +``` + +## Send Application Metrics + +Metrics are enabled by default in Sentry .NET SDK 6.1.0 and later. Use `SentrySdk.Metrics` to send counters, gauges, and distributions from your app. + +See Set Up Metrics for all available metric types and configuration options. + +```csharp +SentrySdk.Metrics.EmitCounter("button_click", 5, + new Dictionary { ["browser"] = "Firefox" }); +SentrySdk.Metrics.EmitGauge("page_load", 15.0, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["page"] = "/home" }); +SentrySdk.Metrics.EmitDistribution("api_latency", 187, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["endpoint"] = "/api/orders" }); +``` + +## Verify Your Setup + +Let's test your setup and confirm that data reaches your Sentry project. +### View Captured Data in Sentry + +Open your Sentry project to view the captured event. + ## Next Steps +At this point, you should have integrated Sentry into your .NET MAUI application. Here's what to explore next: + - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Learn how to [manually capture errors](/platforms/dotnet/usage/) +- Explore [Tracing](/platforms/dotnet/tracing/) diff --git a/docs/platforms/dotnet/guides/winforms/index.mdx b/docs/platforms/dotnet/guides/winforms/index.mdx index 166143d0461d55..0c2e5915b5bd2c 100644 --- a/docs/platforms/dotnet/guides/winforms/index.mdx +++ b/docs/platforms/dotnet/guides/winforms/index.mdx @@ -6,20 +6,16 @@ og_image: /og-images/platforms-dotnet-guides-winforms.png Sentry's .NET SDK works with WinForms applications through the [Sentry NuGet package](https://www.nuget.org/packages/Sentry). It works with WinForms apps running on .NET Framework 4.6.2, .NET Core 3.0, or higher. -## Features - -In addition to capturing errors, you can monitor interactions between multiple services or applications by [enabling tracing](/concepts/key-terms/tracing/). - -Select which Sentry features you'd like to install in addition to Error Monitoring to get the corresponding installation and configuration instructions below. - ## Install - - - ## Configure +**Error Monitoring** starts working as soon as you initialize the SDK. **Logs** sent through `SentrySdk.Logger` and **Application Metrics** need no extra configuration. You'll learn how to send them in [Send Logs](#send-logs) and [Send Application Metrics](#send-application-metrics-). + +This guide also enables **Tracing**. + + After adding the NuGet package, the SDK should be initialized in the program's main entry point, before launching any forms or performing significant work. The options for initialization vary by language. ### C# Initialization @@ -31,6 +27,12 @@ You should also set `Application.SetUnhandledExceptionMode(UnhandledExceptionMod A complete example of the recommended startup is as follows: +The snippet also turns on: + +- Tracing: via `TracesSampleRate` + +Don't need a feature? Remove its options from the snippet. + ```csharp using System; using System.Windows.Forms; @@ -63,14 +65,11 @@ namespace WindowsFormsApp1 Debug = true, // Adds request URL and headers, IP and name for users, etc. - options.SendDefaultPii = true; - - // ___PRODUCT_OPTION_START___ performance - // Set traces_sample_rate to 1.0 to capture 100% of transactions for tracing. - // We recommend adjusting this value in production. + SendDefaultPii = true, + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. TracesSampleRate = 1.0, - - // ___PRODUCT_OPTION_END___ performance // Enable Global Mode since this is a client app IsGlobalModeEnabled = true, @@ -226,16 +225,50 @@ Namespace My End Namespace ``` -## Verify +## Send Logs + +Use `SentrySdk.Logger` to send logs at different levels. These logs are sent without an additional option. + +See Set Up Logs for all available logging methods and formatting options. + +```csharp +SentrySdk.Logger.LogInfo("Order processed"); +SentrySdk.Logger.LogWarning("Rate limit reached for /api/orders"); +``` + +## Send Application Metrics + +Metrics are enabled by default in Sentry .NET SDK 6.1.0 and later. Use `SentrySdk.Metrics` to send counters, gauges, and distributions from your app. + +See Set Up Metrics for all available metric types and configuration options. + +```csharp +SentrySdk.Metrics.EmitCounter("button_click", 5, + new Dictionary { ["browser"] = "Firefox" }); +SentrySdk.Metrics.EmitGauge("page_load", 15.0, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["page"] = "/home" }); +SentrySdk.Metrics.EmitDistribution("api_latency", 187, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["endpoint"] = "/api/orders" }); +``` + +## Verify Your Setup -This snippet includes an intentional error, so you can test that everything is working as soon as you set it up. +Let's test your setup and confirm that data reaches your Sentry project. +### View Captured Data in Sentry + +Open your Sentry project to view the captured event. + ## Resources [Discussion on GitHub `Application.SetUnhandledExceptionMode`](https://github.com/getsentry/sentry-dotnet/issues/176) ## Next Steps +At this point, you should have integrated Sentry into your WinForms application. Here's what to explore next: + - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Learn how to [manually capture errors](/platforms/dotnet/usage/) +- Explore [Tracing](/platforms/dotnet/tracing/) diff --git a/docs/platforms/dotnet/guides/winui/index.mdx b/docs/platforms/dotnet/guides/winui/index.mdx index a0c231388bbbd2..16f84ae9841b24 100644 --- a/docs/platforms/dotnet/guides/winui/index.mdx +++ b/docs/platforms/dotnet/guides/winui/index.mdx @@ -5,19 +5,15 @@ description: "Learn about using Sentry's .NET SDK with the Windows UI Library" Sentry's .NET SDK works with Windows UI Library applications through the [Sentry NuGet package](https://www.nuget.org/packages/Sentry). -## Features - -In addition to capturing errors, you can monitor interactions between multiple services or applications by [enabling tracing](/concepts/key-terms/tracing/). - -Select which Sentry features you'd like to install in addition to Error Monitoring to get the corresponding installation and configuration instructions below. - ## Install + - +## Configure - +**Error Monitoring** starts working as soon as you initialize the SDK. **Logs** sent through `SentrySdk.Logger` and **Application Metrics** need no extra configuration. You'll learn how to send them in [Send Logs](#send-logs) and [Send Application Metrics](#send-application-metrics-). + +This guide also enables **Tracing**. -## Configure (Without Trimming) If you don't have [Trimming](https://learn.microsoft.com/en-us/dotnet/core/deploying/trimming/trimming-options?pivots=dotnet-8-0) enabled when publishing your application then all you need to do is [initialize the SDK with `SentrySdk.Init`](/platforms/dotnet/) in the constructor of your application class (usually `App.xaml.cs`). Sentry's integration for WinUI will automatically capture any unhandled exceptions in your application and send these to Sentry. @@ -30,7 +26,11 @@ Do not initialize the SDK in the `OnLaunched` event of the application or the `H In addition to capturing errors, you can monitor interactions between multiple services or applications by [enabling tracing](/concepts/key-terms/tracing/). -Select which Sentry features you'd like to install in addition to Error Monitoring to get the corresponding installation and configuration instructions below. +The snippet also turns on: + +- Tracing: via `TracesSampleRate` + +Don't need a feature? Remove its options from the snippet. ```csharp using Sentry.Protocol; @@ -50,12 +50,11 @@ sealed partial class App : Application // Adds request URL and headers, IP and name for users, etc. options.SendDefaultPii = true; - // ___PRODUCT_OPTION_START___ performance - // Set TracesSampleRate to 1.0 to capture 100% of transactions for tracing. - // We recommend adjusting this value in production. + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. options.TracesSampleRate = 1.0; - // ___PRODUCT_OPTION_END___ performance // Enable Global Mode since this is a client app. options.IsGlobalModeEnabled = true; @@ -71,7 +70,7 @@ sealed partial class App : Application } ``` -## Configure (With Trimming) +### Configure With Trimming If you have [Trimming](https://learn.microsoft.com/en-us/dotnet/core/deploying/trimming/trimming-options?pivots=dotnet-8-0) enabled when publishing your application then, in addition to [initializing the SDK with `SentrySdk.Init`](/platforms/dotnet/), you must also configure an UnhandledException handler in the constructor of your application class (usually `App.xaml.cs`). @@ -102,12 +101,11 @@ sealed partial class App : Application // Adds request URL and headers, IP and name for users, etc. o.SendDefaultPii = true; - // ___PRODUCT_OPTION_START___ performance - // Set TracesSampleRate to 1.0 to capture 100% of transactions for tracing. - // We recommend adjusting this value in production. + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. o.TracesSampleRate = 1.0; - // ___PRODUCT_OPTION_END___ performance // Enable Global Mode since this is a client app. o.IsGlobalModeEnabled = true; @@ -151,12 +149,46 @@ sealed partial class App : Application } ``` -## Verify +## Send Logs + +Use `SentrySdk.Logger` to send logs at different levels. These logs are sent without an additional option. + +See Set Up Logs for all available logging methods and formatting options. + +```csharp +SentrySdk.Logger.LogInfo("Order processed"); +SentrySdk.Logger.LogWarning("Rate limit reached for /api/orders"); +``` + +## Send Application Metrics + +Metrics are enabled by default in Sentry .NET SDK 6.1.0 and later. Use `SentrySdk.Metrics` to send counters, gauges, and distributions from your app. + +See Set Up Metrics for all available metric types and configuration options. + +```csharp +SentrySdk.Metrics.EmitCounter("button_click", 5, + new Dictionary { ["browser"] = "Firefox" }); +SentrySdk.Metrics.EmitGauge("page_load", 15.0, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["page"] = "/home" }); +SentrySdk.Metrics.EmitDistribution("api_latency", 187, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["endpoint"] = "/api/orders" }); +``` + +## Verify Your Setup -This snippet includes an intentional error, so you can test that everything is working as soon as you set it up. +Let's test your setup and confirm that data reaches your Sentry project. +### View Captured Data in Sentry + +Open your Sentry project to view the captured event. + ## Next Steps +At this point, you should have integrated Sentry into your WinUI application. Here's what to explore next: + - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Learn how to [manually capture errors](/platforms/dotnet/usage/) +- Explore [Tracing](/platforms/dotnet/tracing/) diff --git a/docs/platforms/dotnet/guides/wpf/index.mdx b/docs/platforms/dotnet/guides/wpf/index.mdx index 436f99010e3a3a..f9a14449116498 100644 --- a/docs/platforms/dotnet/guides/wpf/index.mdx +++ b/docs/platforms/dotnet/guides/wpf/index.mdx @@ -5,25 +5,27 @@ description: "Learn more about how Sentry's .NET SDK works with Windows Presenta Sentry's .NET SDK works with Windows Presentation Foundation applications through the [Sentry NuGet package](https://www.nuget.org/packages/Sentry). It works with WPF apps running on .NET Framework 4.6.2, .NET Core 3.0 or higher. -## Features - -In addition to capturing errors, you can monitor interactions between multiple services or applications by [enabling tracing](/concepts/key-terms/tracing/). - -Select which Sentry features you'd like to install in addition to Error Monitoring to get the corresponding installation and configuration instructions below. - ## Install - - - ## Configure +**Error Monitoring** starts working as soon as you initialize the SDK. **Logs** sent through `SentrySdk.Logger` and **Application Metrics** need no extra configuration. You'll learn how to send them in [Send Logs](#send-logs) and [Send Application Metrics](#send-application-metrics-). + +This guide also enables **Tracing**. + + In addition to [initializing the SDK with `SentrySdk.Init`](/platforms/dotnet/), you must configure the WPF specific error handler. The SDK automatically handles `AppDomain.UnhandledException`. On WPF, for production apps (when no debugger is attached), WPF catches exception to show the dialog to the user. You can also configure your app to capture those exceptions before the dialog shows up: +The snippet also turns on: + +- Tracing: via `TracesSampleRate` + +Don't need a feature? Remove its options from the snippet. + ```csharp using System.Windows; @@ -41,13 +43,10 @@ public partial class App : Application // Adds request URL and headers, IP and name for users, etc. options.SendDefaultPii = true; - - // ___PRODUCT_OPTION_START___ performance - // Set traces_sample_rate to 1.0 to capture 100% of transactions for tracing. - // We recommend adjusting this value in production. + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. options.TracesSampleRate = 1.0; - - // ___PRODUCT_OPTION_END___ performance // Enable Global Mode since this is a client app options.IsGlobalModeEnabled = true; @@ -66,12 +65,46 @@ public partial class App : Application } ``` -## Verify +## Send Logs + +Use `SentrySdk.Logger` to send logs at different levels. These logs are sent without an additional option. + +See Set Up Logs for all available logging methods and formatting options. + +```csharp +SentrySdk.Logger.LogInfo("Order processed"); +SentrySdk.Logger.LogWarning("Rate limit reached for /api/orders"); +``` + +## Send Application Metrics + +Metrics are enabled by default in Sentry .NET SDK 6.1.0 and later. Use `SentrySdk.Metrics` to send counters, gauges, and distributions from your app. + +See Set Up Metrics for all available metric types and configuration options. + +```csharp +SentrySdk.Metrics.EmitCounter("button_click", 5, + new Dictionary { ["browser"] = "Firefox" }); +SentrySdk.Metrics.EmitGauge("page_load", 15.0, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["page"] = "/home" }); +SentrySdk.Metrics.EmitDistribution("api_latency", 187, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["endpoint"] = "/api/orders" }); +``` + +## Verify Your Setup -This snippet includes an intentional error, so you can test that everything is working as soon as you set it up. +Let's test your setup and confirm that data reaches your Sentry project. +### View Captured Data in Sentry + +Open your Sentry project to view the captured event. + ## Next Steps +At this point, you should have integrated Sentry into your WPF application. Here's what to explore next: + - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Learn how to [manually capture errors](/platforms/dotnet/usage/) +- Explore [Tracing](/platforms/dotnet/tracing/) diff --git a/docs/platforms/dotnet/guides/xamarin/index.mdx b/docs/platforms/dotnet/guides/xamarin/index.mdx index e4aca0e0cd3671..2e7800b29932c3 100644 --- a/docs/platforms/dotnet/guides/xamarin/index.mdx +++ b/docs/platforms/dotnet/guides/xamarin/index.mdx @@ -19,13 +19,21 @@ The SDK is compatible with the following versions or higher: ## Configure -After you've completed setting up a project in Sentry, Sentry will give you a value which we call a DSN or Data Source Name. It looks a lot like a standard URL, but it's just a representation of the configuration required by the Sentry SDK. It consists of a few pieces, including the protocol, public key, the server address, and the project identifier. +**Error Monitoring** starts working as soon as you initialize the SDK. + +This guide also enables **Tracing**. - +After you've completed setting up a project in Sentry, Sentry will give you a value which we call a DSN or Data Source Name. It looks a lot like a standard URL, but it's just a representation of the configuration required by the Sentry SDK. It consists of a few pieces, including the protocol, public key, the server address, and the project identifier. You should initialize the SDK as early as possible, for an example, the start of OnCreate on MainActivity for Android, and, the top of FinishedLaunching on AppDelegate for iOS). +The snippet also turns on: + +- Tracing: via `TracesSampleRate` + +Don't need a feature? Remove its options from the snippet. + ```csharp SentryXamarin.Init(options => { @@ -36,27 +44,15 @@ SentryXamarin.Init(options => options.Debug = true; // Adds request URL and headers, IP and name for users, etc. options.SendDefaultPii = true; - // ___PRODUCT_OPTION_START___ performance - // Set TracesSampleRate to 1.0 to capture 100% - // of transactions for tracing. - // We recommend adjusting this value in production + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. options.TracesSampleRate = 1.0; - // ___PRODUCT_OPTION_END___ performance }); // App code ``` -## Verify - -Great! Now that you've completed setting up the SDK, maybe you want to quickly test out how Sentry works. Start by capturing an exception: - - - -All you need to do is to [initialize the SDK with `SentryXamarin.Init`](../../), you will not need any additional changes to get the SDK ready to go. - -The SDK automatically handles `AppDomain.UnhandledException` and `Application.UnhandledException`, so you'll not need to worry about trying to Catch Unhandled Exceptions. - ### Xamarin Options The following options are only going to be valid during the SDK initialization. @@ -85,6 +81,17 @@ Note that personally identifiable information (PII) might be included in the scr Disables the automatic Logging of internal Warnings that comes from Xamarin Forms. + +## Verify Your Setup + +Let's test your setup and confirm that data reaches your Sentry project. + + + +### View Captured Data in Sentry + +Open your Sentry project to view the captured event. + ## Troubleshooting For information about Troubleshooting, please visit the [troubleshooting](troubleshooting/) page. @@ -95,4 +102,8 @@ For information about Troubleshooting, please visit the [troubleshooting](troubl ## Next Steps +At this point, you should have integrated Sentry into your Xamarin application. Here's what to explore next: + - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Learn how to [manually capture errors](/platforms/dotnet/usage/) +- Explore [Tracing](/platforms/dotnet/tracing/) diff --git a/docs/platforms/dotnet/index.mdx b/docs/platforms/dotnet/index.mdx index 45a64bc5f8916f..d6803feaf506d3 100644 --- a/docs/platforms/dotnet/index.mdx +++ b/docs/platforms/dotnet/index.mdx @@ -24,47 +24,32 @@ You can use these instructions to run Sentry in an app running on: If you're using a framework, such as ASP.NET Core or MAUI, please select the framework on the drop down on the top left. -## Features - -In addition to capturing errors, you can monitor interactions between multiple services or applications by [enabling tracing](/concepts/key-terms/tracing/). You can also collect and analyze performance profiles from real users with [profiling](/product/profiling/). - -Select which Sentry features you'd like to install in addition to Error Monitoring to get the corresponding installation and configuration instructions below. - ## Install - +Install the `Sentry` NuGet package to add the SDK: -Sentry captures data by using an SDK within your application's runtime. These are platform-specific and allow Sentry to have a deep understanding of how your application works. - -Install the **NuGet** package to add the Sentry dependency: - - +```shell {tabTitle:.NET Core CLI} +dotnet add package Sentry -v {{@inject packages.version('sentry.dotnet') }} +``` - ```shell {tabTitle:.NET Core CLI} - dotnet add package Sentry -v {{@inject packages.version('sentry.dotnet') }} - ``` +```powershell {tabTitle:Package Manager} +Install-Package Sentry -Version {{@inject packages.version('sentry.dotnet') }} +``` - ```powershell {tabTitle:Package Manager} - Install-Package Sentry. -Version {{@inject packages.version('sentry.dotnet') }} - ``` +## Configure - +**Error Monitoring** starts working as soon as you call `SentrySdk.Init()`. **Logs** sent through `SentrySdk.Logger` and **Application Metrics** need no extra configuration. You'll learn how to send them in [Send Logs](#send-logs) and [Send Application Metrics](#send-application-metrics-). - +This guide also enables **Tracing**. **Profiling** is in Alpha and needs .NET 8 or later, so it's a separate step: see [Enable Profiling on .NET 8 and Later](#enable-profiling-on-net-8-and-later). - ```shell {tabTitle:.NET Core CLI} - dotnet add package Sentry.Profiling -v {{@inject packages.version('sentry.dotnet.profiling') }} - ``` - ```powershell {tabTitle:Package Manager} - Install-Package Sentry.Profiling -Version {{@inject packages.version('sentry.dotnet.profiling') }} - ``` +To capture all errors, even the one during the startup of your application, you should initialize the Sentry .NET SDK as soon as possible. - +The snippet also turns on: -## Configure +- Tracing: via `TracesSampleRate` -To capture all errors, even the one during the startup of your application, you should initialize the Sentry .NET SDK as soon as possible. +Don't need a feature? Remove its options from the snippet. ```csharp SentrySdk.Init(options => @@ -73,23 +58,81 @@ SentrySdk.Init(options => options.Debug = true; // Adds request URL and headers, IP and name for users, etc. options.SendDefaultPii = true; - // ___PRODUCT_OPTION_START___ performance - // A fixed sample rate of 1.0 - 100% of all transactions are getting sent + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. options.TracesSampleRate = 1.0f; - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ profiling - // A sample rate for profiling - this is relative to TracesSampleRate - options.ProfilesSampleRate = 1.0f; - // ___PRODUCT_OPTION_END___ profiling }); ``` -## Verify +### Enable Profiling on .NET 8 and Later + + + +Profiling for .NET is in Alpha and needs .NET 8 or later. On .NET Framework, `Sentry.Profiling` installs without a warning, but `AddProfilingIntegration()` doesn't compile. + + + +To profile your app, install the `Sentry.Profiling` package: + +```shell {tabTitle:.NET Core CLI} +dotnet add package Sentry.Profiling -v {{@inject packages.version('sentry.dotnet.profiling') }} +``` + +```powershell {tabTitle:Package Manager} +Install-Package Sentry.Profiling -Version {{@inject packages.version('sentry.dotnet.profiling') }} +``` + +Then add these options to `SentrySdk.Init()`: + +```csharp +// Enables Profiling for 100% of sampled transactions. +options.ProfilesSampleRate = 1.0f; +options.AddProfilingIntegration(); +``` + +See Set Up Profiling for supported platforms and options. + +## Send Logs + +Use `SentrySdk.Logger` to send logs at different levels. These logs are sent without an additional option. + +See Set Up Logs for all available logging methods and formatting options. + +```csharp +SentrySdk.Logger.LogInfo("Order processed"); +SentrySdk.Logger.LogWarning("Rate limit reached for /api/orders"); +``` -This snippet includes an intentional error, so you can test that everything is working as soon as you set it up. +## Send Application Metrics + +Metrics are enabled by default in Sentry .NET SDK 6.1.0 and later. Use `SentrySdk.Metrics` to send counters, gauges, and distributions from your app. + +See Set Up Metrics for all available metric types and configuration options. + +```csharp +SentrySdk.Metrics.EmitCounter("button_click", 5, + new Dictionary { ["browser"] = "Firefox" }); +SentrySdk.Metrics.EmitGauge("page_load", 15.0, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["page"] = "/home" }); +SentrySdk.Metrics.EmitDistribution("api_latency", 187, MeasurementUnit.Duration.Millisecond, + new Dictionary { ["endpoint"] = "/api/orders" }); +``` + +## Verify Your Setup + +Let's test your setup and confirm that data reaches your Sentry project. +### View Captured Data in Sentry + +Open your Sentry project to view the captured event. + ## Next Steps +At this point, you should have integrated Sentry into your .NET application. Here's what to explore next: + - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Learn how to [manually capture errors](/platforms/dotnet/usage/) +- Explore [Tracing](/platforms/dotnet/tracing/) diff --git a/docs/platforms/elixir/crons/troubleshooting.mdx b/docs/platforms/elixir/crons/troubleshooting.mdx index 83e09773daa9a5..73c0b54a62e6fc 100644 --- a/docs/platforms/elixir/crons/troubleshooting.mdx +++ b/docs/platforms/elixir/crons/troubleshooting.mdx @@ -25,8 +25,4 @@ Our current data retention policy is 90 days. - - -Currently, we only support crontab expressions with five fields. - - + diff --git a/docs/platforms/go/common/source-context/index.mdx b/docs/platforms/go/common/source-context/index.mdx index 7b7b4fce2f2678..ac6488a8def747 100644 --- a/docs/platforms/go/common/source-context/index.mdx +++ b/docs/platforms/go/common/source-context/index.mdx @@ -14,7 +14,7 @@ For Go, source context is provided through [SCM Source Context](/integrations/so To use source context with Go: 1. Set up a supported SCM integration. -2. Configure code mappings for your project. +2. Configure [code mappings](/integrations/source-code-mgmt/code-mappings/) for your project. 3. Enable source context for the project. For setup details, see [SCM Source Context](/integrations/source-code-mgmt/source-context/). diff --git a/docs/platforms/go/common/troubleshooting.mdx b/docs/platforms/go/common/troubleshooting.mdx index e5f8ce9dd4f7d8..300c9388ef7f5b 100644 --- a/docs/platforms/go/common/troubleshooting.mdx +++ b/docs/platforms/go/common/troubleshooting.mdx @@ -21,7 +21,7 @@ If your Go stack traces are missing source lines, the most common cause is that Check that: - your project has a supported SCM integration installed -- your code mappings point to the correct repository paths +- your [code mappings](/integrations/source-code-mgmt/code-mappings/) point to the correct repository paths - source context is enabled for the project - the event is associated with a release or branch that Sentry can resolve through your code mappings diff --git a/docs/platforms/godot/configuration/source-context.mdx b/docs/platforms/godot/configuration/source-context.mdx index 4f42f2322ec55e..c172d523808111 100644 --- a/docs/platforms/godot/configuration/source-context.mdx +++ b/docs/platforms/godot/configuration/source-context.mdx @@ -18,8 +18,8 @@ This works for frames in any language — GDScript, To set it up: 1. Install a [supported SCM integration](/integrations/source-code-mgmt/source-context/#prerequisites) for your Sentry organization. -2. Add a code mapping for your project — see the **Stack Trace Linking** section of your SCM provider's docs for the full walkthrough. - - GDScript frames reference scripts by their `res://` path, so set the **Stack Trace Root** to `res://` and the **Source Code Root** to the repository directory containing your `project.godot` — for example, `project/` if your Godot project lives in the `project` folder, or leave it empty if it sits at the repository root. +2. Add a code mapping for your project — see [Code Mappings](/integrations/source-code-mgmt/code-mappings/) for the full walkthrough. + - GDScript frames reference scripts by their `res://` path, so set the **Stack trace prefix** to `res://` and the **Repository prefix** to the repository directory containing your `project.godot` — for example, `project/` if your Godot project lives in the `project` folder, or leave it empty if it sits at the repository root. - C# and native frames use regular file paths, so map them with their own code mappings based on the paths you see in your stack traces. 3. Turn on **Enable SCM Source Context** under your project's **Settings > [General Settings](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/:projectId/) > Client Security**. @@ -41,7 +41,7 @@ This doesn't work for GDScript, which has no debug information files. If frames show no source context with SCM fetching, check that: -- For GDScript frames, the code mapping's stack trace root is `res://` and its source root points to the directory containing `project.godot` in your repository. +- For GDScript frames, the code mapping's stack trace prefix is `res://` and its repository prefix points to the directory containing `project.godot` in your repository. - **Enable SCM Source Context** is turned on in your [project settings](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/:projectId/). - The SCM integration is installed and has access to the repository. - The event is associated with a release whose commit Sentry can resolve — otherwise Sentry falls back to the default branch, which may not match the shipped code. diff --git a/docs/platforms/godot/index.mdx b/docs/platforms/godot/index.mdx index 4c6141db0098a0..677148cbeda27c 100644 --- a/docs/platforms/godot/index.mdx +++ b/docs/platforms/godot/index.mdx @@ -27,24 +27,151 @@ Sentry captures data through our addon for Godot Engine which you can install in ## Configure +**Error Monitoring** starts working as soon as you set your DSN: the SDK automatically captures crashes and Godot runtime errors, such as script and shader errors. **Logs** and **Application Metrics** are enabled by default in SDK 2.0.0 and later, and you'll learn how to send them in [Send Logs](#send-logs) and [Send Application Metrics](#send-application-metrics-). +This guide also enables **Tracing**, which requires SDK 2.2.0 or later. To collect **User Feedback** from players, add the SDK's feedback form or use the feedback API. + +### Initialize the SDK + -## Verify +To configure the SDK in code instead, for example to define a `before_send` callback, turn off **Auto Init** in **Project Settings > Sentry > Options** and call `init()` from a script that extends `SceneTree`. Then enter the script's class name in **Project Settings > Application > Run > Main Loop Type**. A single `init()` call from either GDScript or C# initializes the SDK for both languages. See Programmatic Configuration for details. -Add a `Node` to your test scene and attach a script with the following content: +The snippet also turns on: - +- Tracing: via `traces_sample_rate`, or **Sentry > Options > Tracing > Traces Sample Rate** in Project Settings (turn on **Advanced Settings** to see it). Add spans around operations like level loads with instrumentation. For C#, use the [Sentry .NET tracing API](/platforms/dotnet/tracing/). +- Scene tree attachments: via `attach_scene_tree`, or **Sentry > Options > Attach Scene Tree** in Project Settings. See Scene Tree for details. + +Don't need a feature? Remove its options. + +```gdscript {tabTitle:GDScript} {mdExpandTabs} {filename:ProjectMainLoop.gd} +class_name ProjectMainLoop +extends SceneTree + +func _initialize() -> void: + SentrySDK.init(func(options: SentryOptions) -> void: + options.dsn = "___PUBLIC_DSN___" + # Enables Tracing. + # Set to 1.0 to capture 100% of traces. + # We recommend reducing this value in production. + options.traces_sample_rate = 1.0 + # Attaches scene tree data to events. + options.attach_scene_tree = true + ) +``` + +```csharp {tabTitle:C#} {filename:ProjectMainLoop.cs} +using Godot; +using Sentry; +using Sentry.Godot; + +[GlobalClass] +public partial class ProjectMainLoop : SceneTree +{ + public override void _Initialize() + { + SentrySdk.Init(options => + { + options.Dsn = "___PUBLIC_DSN___"; + // Enables Tracing. + // Set to 1.0 to capture 100% of traces. + // We recommend reducing this value in production. + options.TracesSampleRate = 1.0; + // Attaches scene tree data to events. + options.AttachSceneTree = true; + }); + } +} +``` + +### Get Readable Stack Traces + +The official Godot Engine builds only provide export templates without debug information. To get function names, file paths, and line numbers for native crashes, export your game with export templates that contain debug symbols and upload the debug symbols to Sentry. + +To see GDScript source code around stack trace frames in exported games, set up Source Context. + +### Export for Android + +Exporting for Android with the Sentry SDK requires Godot's Gradle build. Install the Android build template with **Project > Install Android Build Template...**, then turn on **Use Gradle Build** in your Android export preset. See Exporting for Android for the full setup. + +### Capture Errors From C# Code + +C# support requires SDK 2.0.0 or later and the .NET build of Godot Engine 4.5 or later. The addon ships the .NET libraries and adds them to your project's `.csproj` file when you open the project in the editor. Build your project to restore the NuGet package. See C#/.NET Support for details. + +## Send Logs + +Use `SentrySDK.logger` to send logs at different levels, such as `info`, `warn`, or `error`. You can pass any attributes you want and search or filter by them later. Logs are generally available in SDK 1.2.0 and later and enabled by default starting with SDK 2.0.0. + +To also capture Godot's own log output, such as engine errors and `print()` statements, set `godot_logger.log_mask`. It's empty by default. -This snippet includes message capturing, so you can test that everything is working as soon as you set it up. +See Set Up Logs for all available logging methods and configuration options. - +```gdscript {tabTitle:GDScript} {mdExpandTabs} +SentrySDK.logger.info("Level loaded successfully") -Learn more about manually capturing an error or message in our Usage documentation. +SentrySDK.logger.warn("Item configuration not found") - +SentrySDK.logger.debug("Spawning %s with %d units", ["enemies", 5], { + "current_scene": get_tree().current_scene.scene_file_path, + "wave_id": "main_wave_3" +}) +``` -To view and resolve the recorded error, log into [sentry.io](https://sentry.io) and select your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved. +```csharp {tabTitle:C#} +SentrySdk.Logger.LogInfo("Level loaded successfully"); + +SentrySdk.Logger.LogWarning("Item configuration not found"); + +SentrySdk.Logger.LogDebug( + log => + { + log.SetAttribute("current_scene", GetTree().CurrentScene.SceneFilePath); + log.SetAttribute("wave_id", "main_wave_3"); + }, + "Spawning {0} with {1} units", "enemies", 5); +``` + +## Send Application Metrics + +Use `SentrySDK.metrics` to send counters, gauges, and distributions from your game to Sentry. You can pass any attributes you want and search or filter by them later. Metrics require SDK 2.0.0 or later, where they're enabled by default. + +See Set Up Metrics for all available metric types and configuration options. + +```gdscript {tabTitle:GDScript} {mdExpandTabs} +SentrySDK.metrics.count("match_started") + +SentrySDK.metrics.gauge("players_online", lobby.get_player_count()) + +SentrySDK.metrics.distribution("level_load_time", load_time, SentryUnit.millisecond, { + "scene": get_tree().current_scene.name +}) +``` + +```csharp {tabTitle:C#} +SentrySdk.Metrics.EmitCounter("match_started", 1); + +SentrySdk.Metrics.EmitGauge("players_online", lobby.GetPlayerCount()); + +SentrySdk.Metrics.EmitDistribution("level_load_time", loadTime, MeasurementUnit.Duration.Millisecond, new Dictionary +{ + ["scene"] = GetTree().CurrentScene.Name.ToString(), +}); +``` + +## Verify Your Setup + +Add a `Node` to your test scene and attach a script with the following content, then run the scene. The script captures a message, so you can confirm that Sentry receives events from your game. + + + +### View Captured Data in Sentry + +To view and resolve the recorded message, log into [sentry.io](https://sentry.io) and select your project. Select **Issues** in the sidebar, then select the message's title to open a page where you can see detailed information and mark it as resolved. ## Next Steps -- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +At this point, you should have integrated Sentry into your Godot Engine game. Here's what to explore next: + +- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup. +- Learn how to manually capture errors and messages. +- Add tags, breadcrumbs, context, and attachments, such as screenshots, to enrich your events. +- Track crash-free users and sessions with Releases & Health. diff --git a/docs/platforms/java/common/crons/troubleshooting.mdx b/docs/platforms/java/common/crons/troubleshooting.mdx index e36db90305e91d..8cd2690a4650d8 100644 --- a/docs/platforms/java/common/crons/troubleshooting.mdx +++ b/docs/platforms/java/common/crons/troubleshooting.mdx @@ -29,8 +29,4 @@ Our current data retention policy is 90 days. - - -Currently, we only support crontab expressions with five fields. - - + diff --git a/docs/platforms/java/common/source-context/index.mdx b/docs/platforms/java/common/source-context/index.mdx index 512741add48607..2310616e77ee98 100644 --- a/docs/platforms/java/common/source-context/index.mdx +++ b/docs/platforms/java/common/source-context/index.mdx @@ -10,9 +10,9 @@ og_image: /og-images/platforms-java-common-source-context.png ## Setting Up Code Mappings -To use suspect commits and stack trace linking, you'll need to set up a code mapping. This is a mapping between the source code in your repository and the source code in your stack traces. You can [set up code mappings manually in the Sentry UI](/product/issues/suspect-commits/#set-up-code-mappings) or [upload code mappings in bulk via Sentry CLI](/cli/code-mappings/). We recommend using the CLI if your project has many modules. +To use suspect commits and stack trace linking, you'll need to set up a code mapping. This is a mapping between the source code in your repository and the source code in your stack traces. You can [set up code mappings manually in the Sentry UI](/integrations/source-code-mgmt/code-mappings/) or [upload code mappings in bulk via Sentry CLI](/cli/code-mappings/). We recommend using the CLI if your project has many modules. -Use the following steps to determine the correct **Stack Trace Root** **Source Code Root** while setting up your code mapping: +Use the following steps to determine the correct **Stack trace prefix** and **Repository prefix** while setting up your code mapping: First, navigate to a stack trace that you wish to map. Find an **In App** frame, which is denoted by a bubble on the right side of the frame. The Java module will be shown as the first piece of text on the left-hand side of the frame header. Hovering over the module will display the file's absolute path. In the screenshot below, the model is `com.example.vu.android.MainActivity` and the absolute file path is `MainActivity.java`. @@ -20,6 +20,6 @@ First, navigate to a stack trace that you wish to map. Find an **In App** frame, Next, calculate the derived file path. Take the frame `module` and replace all `.` characters with `/`. Then, replace the last item (`MainActivity` in this example) with the absolute path found earlier (`MainActivity.java`). In this example, the derived file path is `com/example/vu/android/MainActivity.java`. -Finally, compare the derived with the path found in your source repository. In this example, the `com/example/vu/android/` folder may match the `src/com/example/vu/android/` folder in the source code. Using that information, set the **Stack Trace Root** to `com/example/vu/android/` and the **Source Code Root** to `src/com/example/vu/android/`. This tells Sentry to replace all file paths beginning in `com/example/vu/android/` with `src/com/example/vu/android/` when searching for the source code. +Finally, compare the derived with the path found in your source repository. In this example, the `com/example/vu/android/` folder may match the `src/com/example/vu/android/` folder in the source code. Using that information, set the **Stack trace prefix** to `com/example/vu/android/` and the **Repository prefix** to `src/com/example/vu/android/`. This tells Sentry to replace all file paths beginning in `com/example/vu/android/` with `src/com/example/vu/android/` when searching for the source code. -Because Sentry will use the first matching code mapping, it is recommended to always provide a non-empty value for the **Stack Trace Root** when possible. An empty value in the **Stack Trace Root** will match all file paths, which will work poorly if multiple code mappings are required. +Because Sentry will use the first matching code mapping, it is recommended to always provide a non-empty value for the **Stack trace prefix** when possible. An empty value in the **Stack trace prefix** will match all file paths, which will work poorly if multiple code mappings are required. diff --git a/docs/platforms/javascript/common/agent-tracing/index.mdx b/docs/platforms/javascript/common/agent-tracing/index.mdx index cbe02f841c9340..1768b8651e0dd6 100644 --- a/docs/platforms/javascript/common/agent-tracing/index.mdx +++ b/docs/platforms/javascript/common/agent-tracing/index.mdx @@ -15,7 +15,7 @@ With Sentry Agent Tracing, you can ## Supported Instrumentation -As of SDK version `11.0.0`, Sentry auto-instruments the most popular AI SDKs and frameworks out of the box — no manual setup is required. Just enable tracing, then pick your AI stack below. Each integration page has the details. +As of SDK version `11.0.0`, Sentry auto-instruments the most popular AI SDKs and frameworks out of the box — you don't need to add their integrations yourself. Just enable tracing, then pick your AI stack below. Each integration page has the details. To group multi-turn chats in Conversations, also [track conversations](#tracking-conversations) in the requests that make AI calls. Tracking Conversations. + ## Supported Operations By default, tracing support is added to the following Anthropic SDK calls: diff --git a/docs/platforms/javascript/common/configuration/integrations/google-genai.mdx b/docs/platforms/javascript/common/configuration/integrations/google-genai.mdx index c60b0695852a70..f8b6df99dc53bf 100644 --- a/docs/platforms/javascript/common/configuration/integrations/google-genai.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/google-genai.mdx @@ -21,12 +21,14 @@ The `googleGenAIIntegration` adds instrumentation for the [`@google/genai`](http ```javascript Sentry.init({ dsn: "___PUBLIC_DSN___", - // Tracing must be enabled for agent tracing to work + // Tracing must be enabled for agent tracing to work. + // `googleGenAIIntegration` is then on by default; add it to `integrations` only to change its options. tracesSampleRate: 1.0, - integrations: [Sentry.googleGenAIIntegration()], }); ``` +To group multi-turn chats in [Conversations](/product/agents/conversations/) and show who started them, set a conversation ID and user in every request that makes AI calls. See Tracking Conversations. + ## Supported Operations By default, tracing support is added to the following Google Gen AI SDK calls: diff --git a/docs/platforms/javascript/common/configuration/integrations/groq.mdx b/docs/platforms/javascript/common/configuration/integrations/groq.mdx index b7eeae12a967ef..89a99cfcfad8c7 100644 --- a/docs/platforms/javascript/common/configuration/integrations/groq.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/groq.mdx @@ -21,12 +21,14 @@ The `groqIntegration` adds instrumentation for the [`groq-sdk`](https://www.npmj ```javascript Sentry.init({ dsn: "___PUBLIC_DSN___", - // Tracing must be enabled for agent tracing to work + // Tracing must be enabled for agent tracing to work. + // `groqIntegration` is then on by default; add it to `integrations` only to change its options. tracesSampleRate: 1.0, - integrations: [Sentry.groqIntegration()], }); ``` +To group multi-turn chats in [Conversations](/product/agents/conversations/) and show who started them, set a conversation ID and user in every request that makes AI calls. See Tracking Conversations. + ## Supported Operations By default, tracing support is added to the following Groq SDK calls: diff --git a/docs/platforms/javascript/common/configuration/integrations/langchain.mdx b/docs/platforms/javascript/common/configuration/integrations/langchain.mdx index 1f45f0711ce0df..f66fe19c6fc568 100644 --- a/docs/platforms/javascript/common/configuration/integrations/langchain.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/langchain.mdx @@ -21,12 +21,14 @@ The `langChainIntegration` adds instrumentation for [`langchain`](https://www.np ```javascript Sentry.init({ dsn: "___PUBLIC_DSN___", - // Tracing must be enabled for agent tracing to work + // Tracing must be enabled for agent tracing to work. + // `langChainIntegration` is then on by default; add it to `integrations` only to change its options. tracesSampleRate: 1.0, - integrations: [Sentry.langChainIntegration()], }); ``` +To group multi-turn chats in [Conversations](/product/agents/conversations/) and show who started them, set a conversation ID and user in every request that makes AI calls. See Tracking Conversations. + ## Supported Operations By default, tracing support is added to the following LangChain operations: diff --git a/docs/platforms/javascript/common/configuration/integrations/langgraph.mdx b/docs/platforms/javascript/common/configuration/integrations/langgraph.mdx index d64592409327b4..7731ec532c4a69 100644 --- a/docs/platforms/javascript/common/configuration/integrations/langgraph.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/langgraph.mdx @@ -21,12 +21,14 @@ The `langGraphIntegration` adds instrumentation for [`@langchain/langgraph`](htt ```javascript Sentry.init({ dsn: "___PUBLIC_DSN___", - // Tracing must be enabled for agent tracing to work + // Tracing must be enabled for agent tracing to work. + // `langGraphIntegration` is then on by default; add it to `integrations` only to change its options. tracesSampleRate: 1.0, - integrations: [Sentry.langGraphIntegration()], }); ``` +To group multi-turn chats in [Conversations](/product/agents/conversations/) and show who started them, set a conversation ID and user in every request that makes AI calls. See Tracking Conversations. + ## Supported Operations By default, tracing support is added to the following LangGraph operations: diff --git a/docs/platforms/javascript/common/configuration/integrations/mistral.mdx b/docs/platforms/javascript/common/configuration/integrations/mistral.mdx index e2b68cd712f15e..af1af5c3795070 100644 --- a/docs/platforms/javascript/common/configuration/integrations/mistral.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/mistral.mdx @@ -21,12 +21,14 @@ The `mistralAIIntegration` adds instrumentation for the [`@mistralai/mistralai`] ```javascript Sentry.init({ dsn: "___PUBLIC_DSN___", - // Tracing must be enabled for agent tracing to work + // Tracing must be enabled for agent tracing to work. + // `mistralAIIntegration` is then on by default; add it to `integrations` only to change its options. tracesSampleRate: 1.0, - integrations: [Sentry.mistralAIIntegration()], }); ``` +To group multi-turn chats in [Conversations](/product/agents/conversations/) and show who started them, set a conversation ID and user in every request that makes AI calls. See Tracking Conversations. + On Deno, preload Sentry's import hook so the Mistral SDK can be instrumented: diff --git a/docs/platforms/javascript/common/configuration/integrations/openai.mdx b/docs/platforms/javascript/common/configuration/integrations/openai.mdx index eb623d3b7ba8fa..b592b9a8c819f6 100644 --- a/docs/platforms/javascript/common/configuration/integrations/openai.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/openai.mdx @@ -21,12 +21,14 @@ The `openAIIntegration` adds instrumentation for the [`openai`](https://www.npmj ```javascript Sentry.init({ dsn: "___PUBLIC_DSN___", - // Tracing must be enabled for agent tracing to work + // Tracing must be enabled for agent tracing to work. + // `openAIIntegration` is then on by default; add it to `integrations` only to change its options. tracesSampleRate: 1.0, - integrations: [Sentry.openAIIntegration()], }); ``` +To group multi-turn chats in [Conversations](/product/agents/conversations/) and show who started them, set a conversation ID and user in every request that makes AI calls. See Tracking Conversations. + ## Supported Operations By default, tracing support is added to the following OpenAI SDK calls: diff --git a/docs/platforms/javascript/common/configuration/integrations/together-ai.mdx b/docs/platforms/javascript/common/configuration/integrations/together-ai.mdx index 7562be4b48ed13..d81bf81412ae77 100644 --- a/docs/platforms/javascript/common/configuration/integrations/together-ai.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/together-ai.mdx @@ -21,12 +21,14 @@ The `togetherAIIntegration` adds instrumentation for the [`together-ai`](https:/ ```javascript Sentry.init({ dsn: "___PUBLIC_DSN___", - // Tracing must be enabled for agent tracing to work + // Tracing must be enabled for agent tracing to work. + // `togetherAIIntegration` is then on by default; add it to `integrations` only to change its options. tracesSampleRate: 1.0, - integrations: [Sentry.togetherAIIntegration()], }); ``` +To group multi-turn chats in [Conversations](/product/agents/conversations/) and show who started them, set a conversation ID and user in every request that makes AI calls. See Tracking Conversations. + ## Supported Operations By default, tracing support is added to the following Together AI SDK calls: diff --git a/docs/platforms/javascript/common/configuration/integrations/vercelai.mdx b/docs/platforms/javascript/common/configuration/integrations/vercelai.mdx index 8f5d5f7a68e213..4e69f515a1a376 100644 --- a/docs/platforms/javascript/common/configuration/integrations/vercelai.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/vercelai.mdx @@ -21,12 +21,14 @@ The `vercelAIIntegration` adds instrumentation for the [`ai`](https://www.npmjs. ```javascript Sentry.init({ dsn: "___PUBLIC_DSN___", - // Tracing must be enabled for agent tracing to work + // Tracing must be enabled for agent tracing to work. + // `vercelAIIntegration` is then on by default; add it to `integrations` only to change its options. tracesSampleRate: 1.0, - integrations: [Sentry.vercelAIIntegration()], }); ``` +To group multi-turn chats in [Conversations](/product/agents/conversations/) and show who started them, set a conversation ID and user in every request that makes AI calls. See Tracking Conversations. + diff --git a/docs/platforms/javascript/common/crons/troubleshooting.mdx b/docs/platforms/javascript/common/crons/troubleshooting.mdx index c5d66427b7fa82..4376efc15f3043 100644 --- a/docs/platforms/javascript/common/crons/troubleshooting.mdx +++ b/docs/platforms/javascript/common/crons/troubleshooting.mdx @@ -30,8 +30,4 @@ Our current data retention policy is 90 days. - - -Currently, we only support crontab expressions with five fields. - - + diff --git a/docs/platforms/javascript/common/troubleshooting/index.mdx b/docs/platforms/javascript/common/troubleshooting/index.mdx index 838e9fb64f5348..27a2e12db5ccfd 100644 --- a/docs/platforms/javascript/common/troubleshooting/index.mdx +++ b/docs/platforms/javascript/common/troubleshooting/index.mdx @@ -808,11 +808,7 @@ error: Uncaught SyntaxError: Unexpected token ':' This is a Deno bug ([denoland/deno#36240](https://github.com/denoland/deno/issues/36240)): while any module hook is registered, Deno loads `.json` files with the wrong format. Express, Fastify, Hapi, Koa and mysql2 all read a JSON file this way. -Remove the `@sentry/deno/import` line from your entry file to start your app again: - -```javascript {filename: main.ts} -import * as Sentry from "npm:@sentry/deno"; -``` +Remove the `--preload=npm:@sentry/deno/import` flag from your `deno run` command to start your app again. Errors, `Deno.serve` and `node:http` spans, logs and metrics all keep working without the hook. You lose the integrations that depend on it, such as `mysql` 2.x and `pg`. Drivers that publish their own diagnostics channels, among them `mysql2` 3.20.0 and later and `ioredis` 5.11.0 and later, are instrumented either way. diff --git a/docs/platforms/javascript/guides/astro/index.mdx b/docs/platforms/javascript/guides/astro/index.mdx index 79f9f86d22fd2a..85729298541b1b 100644 --- a/docs/platforms/javascript/guides/astro/index.mdx +++ b/docs/platforms/javascript/guides/astro/index.mdx @@ -1,6 +1,6 @@ --- title: Astro -description: Learn how to manually set up Sentry in your Astro app and capture your first errors. +description: Learn how to manually set up Sentry in your Astro app and capture your first events. sdk: sentry.javascript.astro categories: - browser @@ -18,11 +18,7 @@ You need: -This SDK currently only works on Node runtimes, such as Node adapter or Vercel -with Lambda functions. If you use Cloudflare Workers or Cloudflare Pages, refer to our [Astro on -Cloudflare guide](/platforms/javascript/guides/cloudflare/frameworks/astro/). -Other non-Node runtimes, like Vercel's Edge runtime, are currently **not -supported**. +This SDK currently only works on Node runtimes, such as Node adapter or Vercel with Lambda functions. If you use Cloudflare Workers or Cloudflare Pages, refer to our [Astro on Cloudflare guide](/platforms/javascript/guides/cloudflare/frameworks/astro/). Other non-Node runtimes, like Vercel's Edge runtime, are currently **not supported**. @@ -30,20 +26,191 @@ supported**. ## Install -Choose the features you want to configure, and this guide will show you how: +### Install the Sentry SDK - +Install the Sentry integration using the `astro` CLI, then install the Profiling package using your preferred package manager: + +```bash {tabTitle:npm} +npx astro add @sentry/astro +npm install @sentry/profiling-node +``` + +```bash {tabTitle:yarn} +yarn astro add @sentry/astro +yarn add @sentry/profiling-node +``` + +```bash {tabTitle:pnpm} +pnpm astro add @sentry/astro +pnpm add @sentry/profiling-node +``` + +## Configure + +**Error Monitoring** starts working as soon as you call `Sentry.init()`. **Logs** and **Application Metrics** need no extra configuration, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing**, **Profiling**, **Session Replay**, and **User Feedback**. - +### Initialize the SDK + +To configure Sentry on your app's client-side and server-side, create a `sentry.client.config.(ts|js)` and `sentry.server.config.(ts|js)` file in the root of your project. +Use the tabs in the code box below to view the client and server configuration snippets. + +The snippets also turn on: + +- Tracing: via `tracesSampleRate` +- Profiling: via `nodeProfilingIntegration()` and `profileSessionSampleRate` +- Session Replay: via `replayIntegration()`, sampled with `replaysSessionSampleRate` and `replaysOnErrorSampleRate` +- User Feedback: via `feedbackIntegration()` + +Don't need a feature? Remove its integration and options from the snippets. + +```typescript {tabTitle:Client config}{filename:sentry.client.config.ts} +import * as Sentry from "@sentry/astro"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + integrations: [ + // enables automatic instrumentation + Sentry.browserTracingIntegration(), + // enables Session Replay + Sentry.replayIntegration(), + // enables User Feedback + Sentry.feedbackIntegration({ colorScheme: "system" }), + ], + + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. + tracesSampleRate: 1.0, + + // Capture replays for 10% of all sessions, + // plus for 100% of sessions with an error + // Requires Sentry.replayIntegration() + replaysSessionSampleRate: 0.1, + replaysOnErrorSampleRate: 1.0, +}); +``` + +```typescript {tabTitle:Server config}{filename:sentry.server.config.ts} +import * as Sentry from "@sentry/astro"; +import { nodeProfilingIntegration } from "@sentry/profiling-node"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + // enables Node Profiling + integrations: [nodeProfilingIntegration()], + + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. + tracesSampleRate: 1.0, + + // Enables Profiling. + // Set to 1.0 to profile every session. + // We recommend reducing this value in production. + profileSessionSampleRate: 1.0, +}); +``` + +### Register the Sentry Integration + +Add the Sentry integration to your `astro.config.mjs`: + +```javascript {filename:astro.config.mjs} +import { defineConfig } from "astro/config"; +import sentry from "@sentry/astro"; + +export default defineConfig({ + integrations: [sentry()], +}); +``` + +### Add Readable Stack Traces With Source Maps + +To upload source maps for clear error stack traces, add your Sentry auth token, organization, and project slugs in the `sentry` options inside `astro.config.mjs`: + +```javascript {filename:astro.config.mjs} +import { defineConfig } from "astro/config"; +import sentry from "@sentry/astro"; + +export default defineConfig({ + integrations: [ + sentry({ + org: "___ORG_SLUG___", + project: "___PROJECT_SLUG___", + // store your auth token in an environment variable + authToken: process.env.SENTRY_AUTH_TOKEN, + }), + ], +}); +``` + +To keep your auth token secure, set the `SENTRY_AUTH_TOKEN` environment variable in your build environment: + + + +```bash {filename:.env.sentry-build-plugin} +SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___ +``` + + + +### Control the Data You Send to Sentry + + + +## Send Logs + + + +If you already use `console`, capture those calls as Sentry Logs with `consoleLoggingIntegration`. +We also provide integrations for: +- Consola +- Pino + +## Send Application Metrics + + + +On Node.js, `nodeRuntimeMetricsIntegration` also collects runtime health metrics automatically. + +## Verify Your Setup + +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. + +Add this button to a page in your Astro app and click it to send a test error: + +```astro + + + +``` + +### View Captured Data in Sentry + +Now, head over to your project on [Sentry.io](https://sentry.io) to view the collected data (it takes a couple of moments for the data to appear). + + + +## Next Steps + +At this point, you should have integrated Sentry into your Astro application. Here's what to explore next: + +- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Set up Agent Tracing to monitor your AI systems +- Set up tunneling to avoid ad blockers blocking Sentry events + + + +- Find various topics in Troubleshooting +- [Get support](https://www.sentry.help/en/) + + diff --git a/docs/platforms/javascript/guides/azure-functions/index.mdx b/docs/platforms/javascript/guides/azure-functions/index.mdx index 731574513496e4..a03dbef012ccd6 100644 --- a/docs/platforms/javascript/guides/azure-functions/index.mdx +++ b/docs/platforms/javascript/guides/azure-functions/index.mdx @@ -1,6 +1,6 @@ --- title: Azure Functions -description: Learn how to manually set up Sentry in your Azure Functions and capture your first errors. +description: Learn how to manually set up Sentry in your Azure Functions and capture your first events. sdk: sentry.javascript.node fallbackGuide: javascript.node categories: @@ -15,14 +15,6 @@ categories: ## Install -Choose the features you want to configure, and this guide will show you how: - - - - - ### Install the Sentry SDK Run the command for your preferred package manager to add `@sentry/node` as a runtime dependency to your application: @@ -31,37 +23,36 @@ Run the command for your preferred package manager to add `@sentry/node` as a ru ## Configure +**Error Monitoring** starts working as soon as you call `Sentry.init()`. **Logs** and **Application Metrics** need no extra configuration, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing** and **Profiling**. + + + +The snippet also turns on: + +- Tracing: via `tracesSampleRate` +- Profiling: via `profileSessionSampleRate` and `nodeProfilingIntegration()` + +Don't need a feature? Remove its integration and options from the snippet. + Make sure to initialize Sentry at the top of your function file before importing any other modules: ```javascript {tabTitle:async} const Sentry = require("@sentry/node"); -// ___PRODUCT_OPTION_START___ profiling const { nodeProfilingIntegration } = require("@sentry/profiling-node"); - -// ___PRODUCT_OPTION_END___ profiling Sentry.init({ dsn: "___PUBLIC_DSN___", - // ___PRODUCT_OPTION_START___ profiling - integrations: [nodeProfilingIntegration()], - // ___PRODUCT_OPTION_END___ profiling - // ___PRODUCT_OPTION_START___ performance - - // Add Performance Monitoring by setting tracesSampleRate - // Set tracesSampleRate to 1.0 to capture 100% of transactions - // We recommend adjusting this value in production - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ profiling - // Enable profiling for a percentage of sessions - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#profileSessionSampleRate + // Enables Profiling. + // Set to 1.0 to profile every session. + // We recommend reducing this value in production. profileSessionSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ profiling }); // your function code @@ -92,80 +83,48 @@ module.exports = async function (context, req) { }; ``` -### Add Readable Stack Traces With Source Maps (Optional) +### Add Readable Stack Traces With Source Maps -### Control the Data You Send to Sentry (Optional) +### Control the Data You Send to Sentry -## Step 4: Verify Your Setup +## Send Logs -Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. + -### Issues +If you're already logging with another library, use an integration to capture those logs as Sentry Logs automatically: +- `consoleLoggingIntegration` for `console` calls +- Consola +- Pino -Let's verify that Sentry captures errors and creates issues in your Sentry project. Add an intentional error in your function: +## Send Application Metrics -```javascript {tabTitle:async} -const Sentry = require("@sentry/node"); - -module.exports = async function (context, req) { - try { - // This function does not exist, triggering an error - await notExistFunction(); - } catch (e) { - Sentry.withScope((scope) => { - scope.setSDKProcessingMetadata({ request: req }); - Sentry.captureException(e); - }); - } + - // Wait for the event to be sent before the function execution ends - await Sentry.flush(2000); +On Node.js, `nodeRuntimeMetricsIntegration` also collects runtime health metrics automatically. - context.res = { - status: 500, - body: "Test error sent to Sentry.", - }; -}; -``` +## Verify Your Setup - -### Tracing +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. -To test tracing, update your function to include a custom span: +Add an intentional error in your function and flush the event before the function execution ends: ```javascript {tabTitle:async} const Sentry = require("@sentry/node"); module.exports = async function (context, req) { - await Sentry.startSpan({ name: "My Custom Span", op: "task" }, async () => { - // Simulate some work - await new Promise((resolve) => setTimeout(resolve, 100)); - }); - - // Wait for the event to be sent before the function execution ends - await Sentry.flush(2000); - - context.res = { - status: 200, - body: "Hello world!", - }; + try { + throw new Error("Sentry Test Error"); + } catch (error) { + Sentry.captureException(error); + await Sentry.flush(2000); + } }; ``` - - - - - - - - - - ### View Captured Data in Sentry Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). @@ -174,14 +133,10 @@ Now, head over to your project on [Sentry.io](https://sentry.io/) to view the co ## Next Steps -At this point, you should have integrated Sentry into your Azure Function and should already be sending data to your Sentry project. - -Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are: +At this point, you should have integrated Sentry into your Azure Functions application. Here's what to explore next: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Continue to customize your configuration -- Learn how to manually capture errors -- Get familiar with [Sentry's product features](/) like tracing, insights, and alerts +- Set up Agent Tracing to monitor your AI systems - Find various topics in Troubleshooting diff --git a/docs/platforms/javascript/guides/bun/index.mdx b/docs/platforms/javascript/guides/bun/index.mdx index ba7b0ba8e49a6b..953542c895b9eb 100644 --- a/docs/platforms/javascript/guides/bun/index.mdx +++ b/docs/platforms/javascript/guides/bun/index.mdx @@ -1,6 +1,6 @@ --- title: Bun -description: Learn how to manually set up Sentry in your Bun app and capture your first errors. +description: Learn how to manually set up Sentry in your Bun app and capture your first events. sdk: sentry.javascript.bun categories: - server @@ -13,14 +13,6 @@ categories: ## Install -Choose the features you want to configure, and this guide will show you how: - - - - - ### Install the SDK Use the Bun package manager to add the Sentry SDK to your application: @@ -31,10 +23,21 @@ bun add @sentry/bun ## Configure +**Error Monitoring** starts working as soon as you call `Sentry.init()`. **Logs** and **Application Metrics** need no extra configuration, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing**. + + + ### Initialize the Sentry SDK Sentry should be initialized as early in your app as possible. -Create a file named `instrument.js` in the root directory of your project and add the following code: +Create a file named `instrument.js` in the root directory of your project and add the code snippet shown below. + +The snippet also turns on: + +- Tracing: via `tracesSampleRate` + +Don't need a feature? Remove its integration and options from the snippet. ```javascript {filename: instrument.js} import * as Sentry from "@sentry/bun"; @@ -42,16 +45,10 @@ import * as Sentry from "@sentry/bun"; // Ensure to call this before importing any other modules! Sentry.init({ dsn: "___PUBLIC_DSN___", - - // ___PRODUCT_OPTION_START___ performance - - // Add Performance Monitoring by setting tracesSampleRate - // Set tracesSampleRate to 1.0 to capture 100% of transactions - // We recommend adjusting this value in production - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance }); ``` @@ -84,64 +81,40 @@ bun --preload ./instrument.js app.js bun --preload ./instrument.js dist/app.js ``` -### Add Readable Stack Traces With Source Maps (Optional) +### Add Readable Stack Traces With Source Maps -### Control the Data You Send to Sentry (Optional) +### Control the Data You Send to Sentry -## Verify Your Setup - -Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. +## Send Logs -### Issues + -First, let's verify that Sentry captures errors and creates issues in your Sentry project. Add the following code snippet to your main application file, which will call an undefined function, triggering an error that Sentry will capture: +If you're already logging with another library, use an integration to capture those logs as Sentry Logs automatically: +- `consoleLoggingIntegration` for `console` calls +- Consola +- Pino -```javascript -setTimeout(() => { - try { - foo(); - } catch (e) { - Sentry.captureException(e); - } -}, 99); -``` +## Send Application Metrics - -### Tracing - -To test your tracing configuration, update the previous code snippet by starting a trace to measure the time it takes for the execution of your code: - -```javascript -Sentry.startSpan( - { - op: "test", - name: "My First Test Transaction", - }, - () => { - setTimeout(() => { - try { - foo(); - } catch (e) { - Sentry.captureException(e); - } - }, 99); - } -); -``` + - +For Bun, `bunRuntimeMetricsIntegration` also collects runtime health metrics automatically. - +## Verify Your Setup - +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. - +Add an intentional error to your main application file: - +```javascript +setTimeout(() => { + throw new Error("Sentry Test Error"); +}, 0); +``` ### View Captured Data in Sentry @@ -151,16 +124,10 @@ Finally, head over to your project on [Sentry.io](https://sentry.io/) to view th ## Next Steps -At this point, you should have integrated Sentry into your Bun application, which should already be sending data to your Sentry project. - -Now's a good time to customize your setup and look into more advanced topics. -Our next recommended steps for you are: +At this point, you should have integrated Sentry into your Bun application. Here's what to explore next: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Extend Sentry to your frontend using one of our [frontend SDKs](/) -- Learn how to manually capture errors -- Continue to customize your configuration -- Get familiar with [Sentry's product features](/product/) like tracing, insights, and alerts +- Set up Agent Tracing to monitor your AI systems diff --git a/docs/platforms/javascript/guides/capacitor/index.mdx b/docs/platforms/javascript/guides/capacitor/index.mdx index 7b8dab639d01e6..247d52ff163d84 100644 --- a/docs/platforms/javascript/guides/capacitor/index.mdx +++ b/docs/platforms/javascript/guides/capacitor/index.mdx @@ -1,6 +1,6 @@ --- title: Capacitor -description: Learn how to set up Sentry in your Capacitor application, capture your first errors and traces, and view them in Sentry. +description: Learn how to set up Sentry in your Capacitor application, capture your first events and traces, and view them in Sentry. sdk: sentry.javascript.capacitor categories: - browser @@ -48,16 +48,8 @@ Both frameworks are fully compatible with the current and beta versions of Sentr ## Configure -Choose the features you want to configure, and this guide will show you how: - - +**Error Monitoring** starts working as soon as you call `Sentry.init()`. **Logs** need no extra configuration, and you'll learn how to send them in step [#3](#send-logs). +This guide also enables **Tracing**, **Session Replay**, and **User Feedback**. @@ -65,201 +57,359 @@ Choose the features you want to configure, and this guide will show you how: Initialize Sentry as early as possible in your application's lifecycle. -If you're using Angular, React, Vue, or Nuxt, make sure to forward the `init` method from the framework's Sentry SDK, as you can see in these code snippets. If you're following the vanilla setup, you don't need to do this. - - - -### Add Readable Stack Traces With Source Maps (Optional) - - - -### Provide Native Debug Information for iOS (Optional) - -You need to provide debug information to Sentry to make the stack-trace information for native crashes on iOS easier to understand. You can provide debug information by [uploading dSYM files](/platforms/javascript/guides/capacitor/dsym/). - -### Control the Data You Send to Sentry (Optional) - - - -## Verify - -Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. +The snippets also turn on: -### Issues +- Tracing: via `tracesSampleRate` +- Session Replay: via `replayIntegration()`, sampled with `replaysSessionSampleRate` and `replaysOnErrorSampleRate` +- User Feedback: via `feedbackIntegration()` -To verify that Sentry captures errors and creates issues in your Sentry project, add the following test button and logic. +Don't need a feature? Remove its integration and options from the snippet. - - Open the page in a browser and click the button to trigger a frontend error. - - - +If you're using Angular, React, Vue, or Nuxt, make sure to forward the `init` method from the framework's Sentry SDK, as you can see in these code snippets. If you're following the vanilla setup, you don't need to do this. -```javascript {tabTitle: Angular 12, 13, 14+} {mdExpandTabs} -@Component({ - selector: "app-root", - template: ` - - ` +```typescript {tabTitle: Angular 14+} {mdExpandTabs} {filename: app.module.ts} +import * as Sentry from "@sentry/capacitor"; +import * as SentryAngular from "@sentry/angular"; + +Sentry.init( + { + dsn: "___PUBLIC_DSN___", + + // Set your release version, such as "getsentry@1.0.0" + release: "my-project-name@", + // Set your dist version, such as "1" + dist: "", + integrations: [ + // Enables automatic instrumentation + Sentry.browserTracingIntegration(), + // enables Session Replay + Sentry.replayIntegration(), + // enables User Feedback + Sentry.feedbackIntegration({ + // Additional integration configuration goes in here + colorScheme: "system", + }), + ], + + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. + tracesSampleRate: 1.0, + + // Limit which URLs receive trace propagation + tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/], + + // Capture replays for 10% of all sessions, + // plus for 100% of sessions with an error + // Requires Sentry.replayIntegration() + replaysSessionSampleRate: 0.1, + replaysOnErrorSampleRate: 1.0, + }, + // Forward the init method from @sentry/angular + SentryAngular.init +); + +@NgModule({ + providers: [ + { + provide: ErrorHandler, + // Attach the Sentry ErrorHandler + useValue: SentryAngular.createErrorHandler(), + }, + { + provide: SentryAngular.TraceService, + deps: [Router], + }, + { + provide: APP_INITIALIZER, + useFactory: () => () => {}, + deps: [SentryAngular.TraceService], + multi: true, + }, + ], }) -class AppComponent { - // ... - throwError(): void { - throw new Error("Sentry Test Error"); - } -} ``` -```javascript {tabTitle: React} - +```typescript {tabTitle: Angular 12, 13} {filename: app.module.ts} +// Requires @sentry/capacitor V0. +import * as Sentry from "@sentry/capacitor"; +import * as SentryAngular from "@sentry/angular-ivy"; + +Sentry.init( + { + dsn: "___PUBLIC_DSN___", + + // Set your release version, such as "getsentry@1.0.0" + release: "my-project-name@", + // Set your dist version, such as "1" + dist: "", + integrations: [ + // Enables automatic instrumentation + new Sentry.BrowserTracing(), + // enables Session Replay + new Sentry.Replay(), + // enables User Feedback + Sentry.feedbackIntegration({ + // Additional integration configuration goes in here + colorScheme: "system", + }), + ], + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. + tracesSampleRate: 1.0, + + // Limit which URLs receive trace propagation + tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/], + + // Capture replays for 10% of all sessions, + // plus for 100% of sessions with an error + // Requires Sentry.replayIntegration() + replaysSessionSampleRate: 0.1, + replaysOnErrorSampleRate: 1.0, + }, + // Forward the init method from @sentry/angular + SentryAngular.init +); + +@NgModule({ + providers: [ + { + provide: ErrorHandler, + // Attach the Sentry ErrorHandler + useValue: SentryAngular.createErrorHandler(), + }, + { + provide: SentryAngular.TraceService, + deps: [Router], + }, + { + provide: APP_INITIALIZER, + useFactory: () => () => {}, + deps: [SentryAngular.TraceService], + multi: true, + }, + ], +}) ``` -```javascript {tabTitle: Vue} - - -export default { - // ... - methods: { - throwError() { - throw new Error('Sentry Error'); - } - } -}; +```typescript {tabTitle: React} {filename: index.tsx} +import * as Sentry from "@sentry/capacitor"; +import * as SentryReact from "@sentry/react"; + +Sentry.init( + { + dsn: "___PUBLIC_DSN___", + + // Set your release version, such as "getsentry@1.0.0" + release: "my-project-name@", + // Set your dist version, such as "1" + dist: "", + integrations: [ + // Enables automatic instrumentation + Sentry.browserTracingIntegration(), + // enables Session Replay + Sentry.replayIntegration(), + // enables User Feedback + Sentry.feedbackIntegration({ + // Additional integration configuration goes in here + colorScheme: "system", + }), + ], + + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. + tracesSampleRate: 1.0, + + // Limit which URLs receive trace propagation + tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/], + + // Capture replays for 10% of all sessions, + // plus for 100% of sessions with an error + // Requires Sentry.replayIntegration() + replaysSessionSampleRate: 0.1, + replaysOnErrorSampleRate: 1.0, + }, + // Forward the init method from @sentry/react + SentryReact.init +); ``` -```html {tabTitle: Nuxt} - - - +```typescript {tabTitle: Vue} {filename: main.ts} +import * as Sentry from "@sentry/capacitor"; +import * as SentryVue from "@sentry/vue"; +import { createApp } from "vue"; + +const app = createApp(App); + +Sentry.init( + { + dsn: "___PUBLIC_DSN___", + + // Vue specific settings. + siblingOptions: { + vueOptions: { + app: app, + attachErrorHandler: false, + attachProps: true, + }, + }, + + // Set your release version, such as "getsentry@1.0.0" + release: "my-project-name@", + // Set your dist version, such as "1" + dist: "", + integrations: [ + // Enables automatic instrumentation + Sentry.browserTracingIntegration(), + // enables Session Replay + Sentry.replayIntegration(), + // enables User Feedback + Sentry.feedbackIntegration({ + // Additional integration configuration goes in here + colorScheme: "system", + }), + ], + + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. + tracesSampleRate: 1.0, + + // Limit which URLs receive trace propagation + tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/], + + // Capture replays for 10% of all sessions, + // plus for 100% of sessions with an error + // Requires Sentry.replayIntegration() + replaysSessionSampleRate: 0.1, + replaysOnErrorSampleRate: 1.0, + }, + + // Forward the init method from @sentry/vue + SentryVue.init +); ``` -```html {tabTitle: Other} - - - +```typescript {tabTitle: Nuxt} {filename: sentry.client.config.ts} +import * as Sentry from "@sentry/capacitor"; +import * as SentryNuxt from "@sentry/nuxt"; + +Sentry.init( + { + dsn: "___PUBLIC_DSN___", + // Set your release version, such as "getsentry@1.0.0" + release: "my-project-name@", + // Set your dist version, such as "1" + dist: "", + integrations: [ + // Enables automatic instrumentation + Sentry.browserTracingIntegration(), + // enables Session Replay + Sentry.replayIntegration(), + // enables User Feedback + Sentry.feedbackIntegration({ + // Additional integration configuration goes in here + colorScheme: "system", + }), + ], + + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. + tracesSampleRate: 1.0, + + // Limit which URLs receive trace propagation + tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/], + + // Capture replays for 10% of all sessions, + // plus for 100% of sessions with an error + // Requires Sentry.replayIntegration() + replaysSessionSampleRate: 0.1, + replaysOnErrorSampleRate: 1.0, + }, + + // Forward the init method from @sentry/nuxt + SentryNuxt.init +); ``` - +```javascript {tabTitle: Other} {filename: main.(ts|js)} +import * as Sentry from "@sentry/capacitor"; +import { feedbackIntegration } from "@sentry/browser"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + + // Set your release version, such as "getsentry@1.0.0" + release: "my-project-name@", + // Set your dist version, such as "1" + dist: "", + integrations: [ + // Enables automatic instrumentation + Sentry.browserTracingIntegration(), + // enables Session Replay + Sentry.replayIntegration(), + // enables User Feedback + feedbackIntegration({ + // Additional integration configuration goes in here + colorScheme: "system", + }), + ], + + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. + tracesSampleRate: 1.0, + + // Limit which URLs receive trace propagation + tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/], + + // Capture replays for 10% of all sessions, + // plus for 100% of sessions with an error + // Requires Sentry.replayIntegration() + replaysSessionSampleRate: 0.1, + replaysOnErrorSampleRate: 1.0, +}); +``` -### Tracing +### Add Readable Stack Traces With Source Maps -To test your tracing configuration, update the previous code snippet and wrap the error in a custom span. -Then, open the page in a browser and click the button to trigger a frontend error and trace. + -```javascript {tabTitle: Angular 12, 13, 14+} {mdExpandTabs} -import * as Sentry from "@sentry/capacitor"; +### Provide Native Debug Information for iOS -@Component({ - selector: "app-root", - template: ` - - ` -}) -class AppComponent { - // ... - throwError(): void { - Sentry.startSpan({ op: "test", name: "Example Frontend Span" }, () => { - throw new Error("Sentry Test Error"); - }); - } -} -``` +You need to provide debug information to Sentry to make the stack-trace information for native crashes on iOS easier to understand. You can provide debug information by [uploading dSYM files](/platforms/javascript/guides/capacitor/dsym/). -```javascript {tabTitle: React} -import * as Sentry from "@sentry/capacitor"; +### Control the Data You Send to Sentry -; -``` + -```javascript {tabTitle: Vue} -import * as Sentry from "@sentry/capacitor"; +## Send Logs - - -export default { - // ... - methods: { - throwError() { - Sentry.startSpan({ op: "test", name: "Example Frontend Span" }, async () => { - throw new Error("Sentry Error"); - }); - } - } -}; -``` + -```html {tabTitle: Nuxt} - +If you already use `console`, capture those calls as Sentry Logs with `consoleLoggingIntegration`. - -``` +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. -```html {tabTitle: Other} - +Add a test button to an existing page. Clicking it throws an error that Sentry captures: - ``` - - - - - - - - ### View Captured Data in Sentry Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). @@ -268,15 +418,10 @@ Now, head over to your project on [Sentry.io](https://sentry.io/) to view the co ## Next Steps -At this point, you should have integrated Sentry into your Capacitor application and should already be sending data to your Sentry project. - -Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are: +At this point, you should have integrated Sentry into your Capacitor application. Here's what to explore next: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup - Learn how to use Sentry with Ionic -- Continue to customize your configuration -- Learn how to manually capture errors -- Make use of framework-specific features, such as [Angular](/platforms/javascript/guides/angular/features/), [Vue](/platforms/javascript/guides/vue/features/), [React](/platforms/javascript/guides/react/features/), or [Nuxt](/platforms/javascript/guides/nuxt/features/) - Find various topics in Troubleshooting diff --git a/docs/platforms/javascript/guides/cloudflare/index.mdx b/docs/platforms/javascript/guides/cloudflare/index.mdx index b82a9bc7d03aeb..76049c2c545523 100644 --- a/docs/platforms/javascript/guides/cloudflare/index.mdx +++ b/docs/platforms/javascript/guides/cloudflare/index.mdx @@ -1,6 +1,6 @@ --- title: Cloudflare -description: "Learn how to manually set up Sentry for Cloudflare Workers and capture your first errors." +description: "Learn how to manually set up Sentry for Cloudflare Workers and capture your first events." sdk: sentry.javascript.cloudflare categories: - server @@ -34,14 +34,6 @@ If you're using any of the listed frameworks, follow their specific setup instru ## Install -Choose the features you want to configure, and this guide will show you how: - - - - - ### Install the Sentry SDK Run the command for your preferred package manager to add the Sentry SDK to your application: @@ -50,6 +42,11 @@ Run the command for your preferred package manager to add the Sentry SDK to your ## Configure +**Error Monitoring** starts working as soon as you configure Sentry. **Logs** and **Application Metrics** need no extra configuration, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing**. + + + This guide sets Sentry up through Vite, which is what we recommend for Cloudflare Workers. The plugin does the wiring at build time, so your Worker code stays untouched. @@ -94,18 +91,22 @@ Create an `instrument.server.ts` file next to your Worker entry, the file that ` The name is fixed. The plugin looks for `instrument.server` with a `.ts`, `.mts`, `.js`, `.mjs` or `.cjs` extension, and passes its default export to `withSentry`. Use `defineCloudflareOptions` to get the options type-checked. +The snippet also turns on: + +- Tracing: via `tracesSampleRate` + +Don't need a feature? Remove its integration and options from the snippet. + ```typescript {filename:src/instrument.server.ts} import { defineCloudflareOptions } from "@sentry/cloudflare"; export default defineCloudflareOptions((env) => ({ dsn: "___PUBLIC_DSN___", - // ___PRODUCT_OPTION_START___ performance - // Set tracesSampleRate to 1.0 to capture 100% of spans for tracing. - // Learn more at - // https://docs.sentry.io/platforms/javascript/guides/cloudflare/configuration/options/#tracesSampleRate + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance })); ``` @@ -115,104 +116,65 @@ If you don't add an `instrument.server.*` file, the SDK reads its configuration -### Add Readable Stack Traces With Source Maps (Optional) +### Add Readable Stack Traces With Source Maps -### Control the Data You Send to Sentry (Optional) +### Control the Data You Send to Sentry -## Verify Your Setup +### Known Limitations -Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. +#### Span Durations -### Issues +Server-side spans will display `0ms` for their durations. In the Cloudflare Workers runtime, `performance.now()` and `Date.now()` only advance after I/O occurs. CPU-bound operations will show zero duration. This is a security measure Cloudflare implements to [mitigate against timing attacks](https://developers.cloudflare.com/workers/runtime-apis/performance/). -First, let's make sure Sentry is correctly capturing errors and creating issues in your project. +This is expected behavior in the Cloudflare Workers environment and affects all frameworks deployed to Cloudflare Workers, including Next.js, Astro, Remix, and others. -Add the following code snippet to your main worker file to create a `/debug-sentry` route that triggers an error when called: -```javascript {filename:index.js} -export default { - async fetch(request) { - const url = new URL(request.url); +## Send Logs - if (url.pathname === "/debug-sentry") { - throw new Error("My first Sentry error!"); - } + - // Your existing routes and logic here... - return new Response("..."); - }, -}; -``` +If you're already logging with `console` or Consola, you can capture those logs with our console integrations. + +## Send Application Metrics + + - -### Tracing -To test your tracing configuration, update the previous code snippet by starting a trace to measure the time it takes to run your code. +## Verify Your Setup + +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. -```javascript {filename:index.js} -import * as Sentry from "@sentry/cloudflare"; +Add a route to your Worker that throws an error: +```javascript export default { async fetch(request) { const url = new URL(request.url); if (url.pathname === "/debug-sentry") { - await Sentry.startSpan( - { - op: "test", - name: "My First Test Span", - }, - async () => { - await new Promise((resolve) => setTimeout(resolve, 100)); // Wait for 100ms - throw new Error("My first Sentry error!"); - } - ); + throw new Error("Sentry Test Error"); } - // Your existing routes and logic here... return new Response("..."); }, }; ``` - - - - - - - - - - ### View Captured Data in Sentry Now, head over to your project on [Sentry.io](https://sentry.io) to view the collected data (it takes a couple of moments for the data to appear). -## Known Limitations - -### Span Durations - -Server-side spans will display `0ms` for their durations. In the Cloudflare Workers runtime, `performance.now()` and `Date.now()` only advance after I/O occurs. CPU-bound operations will show zero duration. This is a security measure Cloudflare implements to [mitigate against timing attacks](https://developers.cloudflare.com/workers/runtime-apis/performance/). - -This is expected behavior in the Cloudflare Workers environment and affects all frameworks deployed to Cloudflare Workers, including Next.js, Astro, Remix, and others. - ## Next Steps -At this point, you should have integrated Sentry and should already be sending data to your Sentry project. - -Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are: +At this point, you should have integrated Sentry into your Cloudflare Worker. Here's what to explore next: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Learn how to [manually capture errors](/platforms/javascript/guides/cloudflare/usage/) -- Continue to [customize your configuration](/platforms/javascript/guides/cloudflare/configuration/) -- Make use of [Cloudflare-specific features](/platforms/javascript/guides/cloudflare/features/) -- Get familiar with [Sentry's product features](/product/) like tracing, insights, and alerts +- Set up Agent Tracing to monitor your AI systems diff --git a/docs/platforms/javascript/guides/deno/index.mdx b/docs/platforms/javascript/guides/deno/index.mdx index 098dfe3040692f..41329f9bb689a6 100644 --- a/docs/platforms/javascript/guides/deno/index.mdx +++ b/docs/platforms/javascript/guides/deno/index.mdx @@ -1,6 +1,6 @@ --- title: Deno -description: Learn how to manually set up Sentry in your Deno app and capture your first errors. +description: Learn how to manually set up Sentry in your Deno app and capture your first events. sdk: sentry.javascript.deno categories: - server @@ -19,25 +19,16 @@ This SDK is currently in **beta**. Beta features are still in progress and may h ## Install -Choose the features you want to configure, and this guide will show you how: - - - - - ### Import the Sentry SDK -Import the Sentry Deno SDK directly from the npm registry, before importing any other modules. The first line registers the hook that instruments your database drivers, message queues, AI libraries and web frameworks. It only works as the first import of your entry file: +Import the Sentry Deno SDK directly from the npm registry, before importing any other modules: ```javascript {filename: main.ts} -import "___SDK_PACKAGE___/import"; import * as Sentry from "___SDK_PACKAGE___"; // your other imports ``` -The hook reads your dependencies from a local `node_modules` directory, not from Deno's global npm cache. Set `nodeModulesDir` in your `deno.json`: +The Sentry import hook, which you load when you [start your app](#start-your-app), reads your dependencies from a local `node_modules` directory, not from Deno's global npm cache. Set `nodeModulesDir` in your `deno.json`: ```json {filename: deno.json} { @@ -50,36 +41,43 @@ The hook reads your dependencies from a local `node_modules` directory, not from ## Configure +**Error Monitoring** starts working as soon as you call `Sentry.init()`. **Logs** and **Application Metrics** need no extra configuration, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing**. + + + ### Initialize the Sentry SDK -Initialize Sentry as early as possible in your app: +Initialize Sentry as early as possible in your app. + +The snippet also turns on: + +- Tracing: via `tracesSampleRate` + +Don't need a feature? Remove its integration and options from the snippet. ```javascript {filename: main.ts} -import "___SDK_PACKAGE___/import"; import * as Sentry from "___SDK_PACKAGE___"; // your other imports Sentry.init({ dsn: "___PUBLIC_DSN___", - - // ___PRODUCT_OPTION_START___ performance - - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for performance monitoring. - // We recommend adjusting this value in production - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance }); ``` -### Grant Permissions +### Start Your App + +Load the Sentry import hook with the `--preload` flag. The hook instruments your database drivers, message queues, AI libraries and web frameworks. An `import` statement in your entry file is too late for packages that ship ES modules, because Deno loads every module that your entry file imports before it runs any of them. Deno blocks access to the network, the file system and system information until you grant it. Start your app with all four permissions so that the SDK can send complete events. Add the other hosts your app talks to, separated by commas: ```bash deno run \ + --preload=___SDK_PACKAGE___/import \ --allow-net=___ORG_INGEST_DOMAIN___ \ --allow-env \ --allow-read=. \ @@ -89,75 +87,48 @@ deno run \ -| Flag | What it gives you | -| -------------------------------- | -------------------------------------------------------------------------------------------- | -| `--allow-net=` | Delivery of events to Sentry. If a host is missing, Deno names it in the error. | -| `--allow-env` | The import hook. Without it, your app stops at start with `NotCapable: Requires env access`. | -| `--allow-read=.` | Source code in stack traces, and `app:///` paths instead of absolute paths. | -| `--allow-sys=hostname,osRelease` | The server name and the operating system version on events. | +| Flag | What it gives you | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--allow-net=` | Delivery of events to Sentry. If a host is missing, Deno names it in the error. | +| `--allow-env` | The import hook. Without it, your app stops at start with `NotCapable: Requires env access`. | +| `--allow-read=.` | The import hook, source code in stack traces, and `app:///` paths instead of absolute paths. Without it, your app stops at start with `NotCapable: Requires read access`. | +| `--allow-sys=hostname,osRelease` | The server name and the operating system version on events. | -If you omit `--allow-read` or `--allow-sys`, the SDK sends events without that data and prints no warning. +If you omit `--allow-sys`, the SDK sends events without that data and prints no warning. -### Add Readable Stack Traces With Source Maps (Optional) +### Add Readable Stack Traces With Source Maps -### Control the Data You Send to Sentry (Optional) +### Control the Data You Send to Sentry -## Verify Your Setup - -Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. - -### Issues +## Send Logs -First, let's verify that Sentry captures errors and creates issues in your Sentry project. Add the following code snippet to your main application file, which will call an undefined function, triggering an error that Sentry will capture: + -```javascript -setTimeout(() => { - try { - foo(); - } catch (e) { - Sentry.captureException(e); - } -}, 99); -``` +If you're already logging with `console` or Consola, you can capture those logs with our console integrations. - -### Tracing +## Send Application Metrics -To test your tracing configuration, update the previous code snippet by starting a trace to measure the time it takes for the execution of your code: + -```javascript -Sentry.startSpan( - { - op: "test", - name: "My First Test Transaction", - }, - () => { - setTimeout(() => { - try { - foo(); - } catch (e) { - Sentry.captureException(e); - } - }, 99); - } -); -``` +For Deno, `denoRuntimeMetricsIntegration` also collects runtime health metrics automatically. - - - +## Verify Your Setup - +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. - +Add an intentional error to your application: - +```javascript +setTimeout(() => { + throw new Error("Sentry Test Error"); +}, 0); +``` ### View Captured Data in Sentry @@ -167,15 +138,10 @@ Finally, head over to your project on [Sentry.io](https://sentry.io/) to view th ## Next Steps -At this point, you should have integrated Sentry into your Deno application and should already be sending data to your Sentry project. - -Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are: +At this point, you should have integrated Sentry into your Deno application. Here's what to explore next: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Extend Sentry to your frontend using one of our [frontend SDKs](/) -- Learn how to manually capture errors -- Continue to customize your configuration -- Get familiar with [Sentry's product features](/product/) like tracing, insights, and alerts +- Set up Agent Tracing to monitor your AI systems diff --git a/docs/platforms/javascript/guides/effect/index.mdx b/docs/platforms/javascript/guides/effect/index.mdx index 9c91a891e8b693..382fb41e82640b 100644 --- a/docs/platforms/javascript/guides/effect/index.mdx +++ b/docs/platforms/javascript/guides/effect/index.mdx @@ -1,7 +1,7 @@ --- title: Effect sdk: sentry.javascript.effect -description: Learn how to set up and configure Sentry in your Effect application, capture your first errors, and view them in Sentry. +description: Learn how to set up and configure Sentry in your Effect application, capture your first events and view them in Sentry. categories: - browser - server @@ -24,14 +24,6 @@ This guide will show you how to integrate Sentry into your [Effect](https://effe ## Install -Choose the features you want to configure, and this guide will show you how: - - - - - ### Install the Sentry SDK Run the command for your preferred package manager to add the Sentry SDK to your application. @@ -50,6 +42,11 @@ pnpm add @sentry/effect ## Configure +**Error Monitoring** starts working as soon as you provide `Sentry.effectLayer()`. **Logs** and **Application Metrics** need no extra SDK configuration. To forward Effect-native logs and metrics, use the Sentry Effect logger and metrics layers shown in this guide. You'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing**. + + + The SDK provides an `effectLayer` that initializes Sentry. You can compose it with additional Effect layers to enable tracing, logging, and metrics. The `effectLayer`, `SentryEffectTracer`, `SentryEffectLogger`, and `SentryEffectMetricsLayer` exports are the same for Effect v3 and v4. The only difference between versions is how you compose layers for tracing and logging, which is covered in the snippets below. ### Effect v3 @@ -61,43 +58,38 @@ The SDK provides an `effectLayer` that initializes Sentry. You can compose it wi In both cases, use `Layer.setTracer` to configure tracing and `Logger.replace` to configure logging. +The snippets also turn on: + +- Tracing: via `tracesSampleRate` and the Effect tracer layer +- Logs: via `SentryEffectLogger` +- Application Metrics: via `SentryEffectMetricsLayer` + +Don't need a feature? Remove its layer and options from the snippet. + ```typescript {tabTitle: Server} {filename: main.ts} import * as Sentry from "@sentry/effect"; import { NodeRuntime } from "@effect/platform-node"; -// ___PRODUCT_OPTION_START___ logs import * as Logger from "effect/Logger"; -// ___PRODUCT_OPTION_END___ logs import * as Layer from "effect/Layer"; import { HttpLive } from "./Http.js"; const SentryLive = Layer.mergeAll( Sentry.effectLayer({ dsn: "___PUBLIC_DSN___", - // ___PRODUCT_OPTION_START___ performance - - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for tracing. - // We recommend adjusting this value in production. - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance }), - // ___PRODUCT_OPTION_START___ performance // Enable Effect tracing Layer.setTracer(Sentry.SentryEffectTracer), - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ logs // Forward Effect logs to Sentry Logger.replace(Logger.defaultLogger, Sentry.SentryEffectLogger), - // ___PRODUCT_OPTION_END___ logs - // ___PRODUCT_OPTION_START___ metrics // Forward Effect metrics to Sentry Sentry.SentryEffectMetricsLayer - // ___PRODUCT_OPTION_END___ metrics ); const MainLive = HttpLive.pipe(Layer.provide(SentryLive)); @@ -107,35 +99,24 @@ MainLive.pipe(Layer.launch, NodeRuntime.runMain); ```typescript {tabTitle: Client} {filename: main.ts} import * as Sentry from "@sentry/effect"; -// ___PRODUCT_OPTION_START___ logs import { Logger } from "effect"; -// ___PRODUCT_OPTION_END___ logs import { Layer } from "effect"; const SentryLive = Layer.mergeAll( Sentry.effectLayer({ dsn: "___PUBLIC_DSN___", - // ___PRODUCT_OPTION_START___ performance - - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for tracing. - // We recommend adjusting this value in production. - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, integrations: [Sentry.browserTracingIntegration()], - // ___PRODUCT_OPTION_END___ performance }), - // ___PRODUCT_OPTION_START___ performance // Enable Effect tracing for the browser Layer.setTracer(Sentry.SentryEffectTracer), - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ logs // Forward Effect logs to Sentry Logger.replace(Logger.defaultLogger, Sentry.SentryEffectLogger) - // ___PRODUCT_OPTION_END___ logs ); const MainLive = YourAppLayer.pipe(Layer.provide(SentryLive)); @@ -152,41 +133,28 @@ With SDK version 10.75.0 or higher, `effectLayer` also registers a Sentry `Error ```typescript {tabTitle: Server} {filename: main.ts} import * as Sentry from "@sentry/effect"; import { NodeRuntime } from "@effect/platform-node"; -// ___PRODUCT_OPTION_START___ logs import * as Logger from "effect/Logger"; -// ___PRODUCT_OPTION_END___ logs import * as Layer from "effect/Layer"; -// ___PRODUCT_OPTION_START___ performance import * as Tracer from "effect/Tracer"; -// ___PRODUCT_OPTION_END___ performance import { HttpLive } from "./Http.js"; const SentryLive = Layer.mergeAll( Sentry.effectLayer({ dsn: "___PUBLIC_DSN___", - // ___PRODUCT_OPTION_START___ performance - - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for tracing. - // We recommend adjusting this value in production. + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance }), - // ___PRODUCT_OPTION_START___ performance // Enable Effect tracing Layer.succeed(Tracer.Tracer, Sentry.SentryEffectTracer), - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ logs // Forward Effect logs to Sentry Logger.layer([Sentry.SentryEffectLogger]), - // ___PRODUCT_OPTION_END___ logs - // ___PRODUCT_OPTION_START___ metrics // Forward Effect metrics to Sentry Sentry.SentryEffectMetricsLayer - // ___PRODUCT_OPTION_END___ metrics ); const MainLive = HttpLive.pipe(Layer.provide(SentryLive)); @@ -196,129 +164,73 @@ MainLive.pipe(Layer.launch, NodeRuntime.runMain); ```typescript {tabTitle: Client} {filename: main.ts} import * as Sentry from "@sentry/effect"; -// ___PRODUCT_OPTION_START___ logs import * as Logger from "effect/Logger"; -// ___PRODUCT_OPTION_END___ logs import * as Layer from "effect/Layer"; -// ___PRODUCT_OPTION_START___ performance import * as Tracer from "effect/Tracer"; -// ___PRODUCT_OPTION_END___ performance const SentryLive = Layer.mergeAll( Sentry.effectLayer({ dsn: "___PUBLIC_DSN___", - // ___PRODUCT_OPTION_START___ performance - - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for tracing. - // We recommend adjusting this value in production. + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, integrations: [Sentry.browserTracingIntegration()], - // ___PRODUCT_OPTION_END___ performance }), - // ___PRODUCT_OPTION_START___ performance // Enable Effect tracing Layer.succeed(Tracer.Tracer, Sentry.SentryEffectTracer), - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ logs // Forward Effect logs to Sentry Logger.layer([Sentry.SentryEffectLogger]) - // ___PRODUCT_OPTION_END___ logs ); const MainLive = YourAppLayer.pipe(Layer.provide(SentryLive)); ``` -### Add Readable Stack Traces With Source Maps (Optional) +### Add Readable Stack Traces With Source Maps -### Control the Data You Send to Sentry (Optional) +### Control the Data You Send to Sentry -## Verify - -Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. +## Send Logs -### Issues +The Effect logger layer forwards `Effect.log` messages to Sentry. The v3 and v4 layer setup is included in the configuration snippets above. -To verify that Sentry captures errors and creates issues in your Sentry project, add a test error: +See Set Up Logs for logging methods and message formatting. ```typescript import { Effect } from "effect"; -import * as Sentry from "@sentry/effect"; const program = Effect.gen(function* () { - yield* Effect.fail(new Error("Sentry Test Error")); -}); - -// Run with your layer that includes Sentry.effectLayer -``` - - -### Tracing - -To test your tracing configuration, update the previous code snippet to create a custom span: - -```typescript -import { Effect } from "effect"; -import * as Sentry from "@sentry/effect"; - -const program = Effect.gen(function* () { - yield* Effect.gen(function* () { - // Simulate some work - yield* Effect.sleep("100 millis"); - yield* Effect.fail(new Error("Sentry Test Error")); - }).pipe( - Effect.withSpan("My First Test Transaction", { - attributes: { op: "test" }, - }) + yield* Effect.log("User example action completed"); + yield* Effect.logWarning("Slow operation detected").pipe( + Effect.annotateLogs({ operation: "data_fetch", duration: "3500ms" }) ); }); ``` - +## Send Application Metrics + + - +## Verify Your Setup -### Logs +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. -To verify that Sentry catches your logs, add some log statements to your application: +Run an Effect that fails using the layer that includes `Sentry.effectLayer()`: ```typescript import { Effect } from "effect"; -import * as Sentry from "@sentry/effect"; - -const program = Effect.gen(function* () { - yield* Effect.log("User example action completed"); - yield* Effect.logWarning("Slow operation detected").pipe( - Effect.annotateLogs({ - operation: "data_fetch", - duration: "3500ms", - }) - ); +const program = Effect.fail(new Error("Sentry Test Error")); - yield* Effect.logError("Validation failed").pipe( - Effect.annotateLogs({ - field: "email", - reason: "Invalid email", - }) - ); -}); +// Run with your layer that includes Sentry.effectLayer(). ``` - - - - - - - - ### View Captured Data in Sentry Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). @@ -327,10 +239,10 @@ Now, head over to your project on [Sentry.io](https://sentry.io/) to view the co ## Next Steps +At this point, you should have integrated Sentry into your Effect application. Here's what to explore next: + - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Learn how to [manually capture errors](/platforms/javascript/guides/effect/usage/) -- Continue to [customize your configuration](/platforms/javascript/guides/effect/configuration/) -- Get familiar with [Sentry's product features](/product/) like tracing, insights, and alerts +- Set up Agent Tracing to monitor your AI systems diff --git a/docs/platforms/javascript/guides/electron/index.mdx b/docs/platforms/javascript/guides/electron/index.mdx index acd7adcda290e1..9d867f486fc7e9 100644 --- a/docs/platforms/javascript/guides/electron/index.mdx +++ b/docs/platforms/javascript/guides/electron/index.mdx @@ -1,6 +1,6 @@ --- title: Electron -description: "Learn how to manually set up Sentry in your Electron app and capture your first errors." +description: "Learn how to manually set up Sentry in your Electron app and capture your first events." sdk: sentry.javascript.electron categories: - desktop @@ -30,40 +30,36 @@ pnpm add @sentry/electron ## Configure -Choose the features you want to configure, and this guide will show you how: - - +**Error Monitoring** starts working as soon as you call `Sentry.init()`. **Logs** and **Application Metrics** need no extra configuration, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing**, **Session Replay**, and **User Feedback**. You should initialize the SDK in both the `main` process and every `renderer` process you spawn. +Don't need a feature? Remove its integration and options from the respective snippet. ### Configure the Main Process -Initialize the SDK in your Electron `main` process as early as possible: +Initialize the SDK in your Electron `main` process as early as possible. + +The main process snippets also turns on: + +- Tracing: via `tracesSampleRate` and `startupTracingIntegration()` ```javascript import * as Sentry from "@sentry/electron/main"; Sentry.init({ dsn: "___PUBLIC_DSN___", - // ___PRODUCT_OPTION_START___ performance - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for performance monitoring. - // We recommend adjusting this value in production - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - integrations: [Sentry.startupTracingIntegration()], - // ___PRODUCT_OPTION_END___ performance + integrations: [ + // Enables startup tracing in the main process + Sentry.startupTracingIntegration(), + ], }); ``` @@ -71,42 +67,38 @@ Sentry.init({ Initialize the SDK in your Electron renderer processes as early as possible. All renderer events are sent through the main process so passing `dsn`, `release` or `environment` to renderer `init` will have no effect. +The renderer process snippet also turns on: + +- Tracing: via `tracesSampleRate` and `browserTracingIntegration()` +- Session Replay: via `replayIntegration()`, sampled with `replaysSessionSampleRate` and `replaysOnErrorSampleRate` +- User Feedback: via `feedbackIntegration()` + ```javascript import * as Sentry from "@sentry/electron/renderer"; Sentry.init({ integrations: [ - // ___PRODUCT_OPTION_START___ performance + // enables automatic instrumentation Sentry.browserTracingIntegration(), - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ session-replay + // enables Session Replay Sentry.replayIntegration(), - // ___PRODUCT_OPTION_END___ session-replay - // ___PRODUCT_OPTION_START___ user-feedback + // enables User Feedback Sentry.feedbackIntegration({ - // Additional SDK configuration goes in here, for example: + // Additional integration configuration goes in here colorScheme: "system", }), - // ___PRODUCT_OPTION_END___ user-feedback ], - // ___PRODUCT_OPTION_START___ performance - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for performance monitoring. - // We recommend adjusting this value in production - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ session-replay - // Capture Replay for 10% of all sessions, + // Capture replays for 10% of all sessions, // plus for 100% of sessions with an error - // Learn more at - // https://docs.sentry.io/platforms/javascript/session-replay/configuration/#general-integration-configuration + // Requires Sentry.replayIntegration() replaysSessionSampleRate: 0.1, replaysOnErrorSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ session-replay }); ``` @@ -166,81 +158,39 @@ init( ); ``` -### Add Readable Stack Traces With Source Maps (Optional) +### Add Readable Stack Traces With Source Maps -### Control the Data You Send to Sentry (Optional) +### Control the Data You Send to Sentry -## Verify Your Setup - -Let's test your setup and confirm that Sentry is working correctly. - -### Issues - -**Main process error** - -Add an event listener that throws an error in your main process: - -```javascript -import { app } from "electron"; -import * as Sentry from "@sentry/electron/main"; - -app.on("ready", () => { - throw new Error("Sentry test error in main process"); -}); -``` - -**Renderer process error** +## Send Logs -Add a test button in one of your HTML pages: + -```html {filename: index.html} - - - -``` +If you're already logging with another library, use an integration to capture those logs as Sentry Logs automatically: +- `consoleLoggingIntegration` for `console` calls +- Consola +- Pino -Then, in your renderer, add the following: +## Send Application Metrics - - Finally, start your app and trigger two errors that Sentry will capture: one from the - main process and one from the renderer. - + -```javascript -document.getElementById("testError").addEventListener("click", () => { - throw new Error("Sentry test error in renderer process"); -}); -``` - - -### Tracing +## Verify Your Setup -To test tracing in your renderer, start a trace to measure the time it takes to execute your code. +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. -Then, start your app and trigger two errors that Sentry will capture: one from the main process and one from the renderer. It will also start a trace with the defined name. +Add a test button to one of your renderer pages. Clicking it throws an error that Sentry captures: ```javascript document.getElementById("testError").addEventListener("click", () => { - Sentry.startSpan({ op: "test", name: "Renderer test span" }, () => { - throw new Error("Sentry test error in renderer process"); - }); + throw new Error("Sentry Test Error"); }); ``` - - - - - - - - - - ### View Captured Data in Sentry Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). @@ -249,15 +199,10 @@ Now, head over to your project on [Sentry.io](https://sentry.io/) to view the co ## Next Steps -At this point, you should have integrated Sentry into your Electron application and should already be sending data to your Sentry project. - -Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are: +At this point, you should have integrated Sentry into your Electron application. Here's what to explore next: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Continue to customize your configuration -- Learn how to manually capture errors -- Make use of Electron-specific features -- Get familiar with [Sentry's product features](/product/) like tracing, insights, and alerts +- Explore Electron-specific features diff --git a/docs/platforms/javascript/guides/elysia/index.mdx b/docs/platforms/javascript/guides/elysia/index.mdx index 7e1cf220de0a05..562cf1f120bead 100644 --- a/docs/platforms/javascript/guides/elysia/index.mdx +++ b/docs/platforms/javascript/guides/elysia/index.mdx @@ -1,6 +1,6 @@ --- title: Elysia -description: Learn how to set up Sentry in your Elysia app to capture errors and monitor performance. +description: Learn how to set up Sentry in your Elysia app and capture your first events. sdk: sentry.javascript.elysia fallbackGuide: javascript.bun categories: @@ -27,23 +27,10 @@ You need: ## Install -Choose the features you want to configure, and this guide will show you how: - - - - - ### Install the Sentry SDK Run the command for your runtime and preferred package manager to add the Sentry SDK to your application: - - You do **not** need `@elysiajs/opentelemetry`. The `@sentry/elysia` SDK - handles all instrumentation natively. - - ```bash {tabTitle:Bun} {mdExpandTabs} bun add @sentry/elysia ``` @@ -56,25 +43,36 @@ yarn add @sentry/elysia @elysiajs/node pnpm add @sentry/elysia @elysiajs/node ``` + + You do **not** need `@elysiajs/opentelemetry`. The `@sentry/elysia` SDK + handles all instrumentation natively. + + ## Configure +**Error Monitoring** starts working as soon as you call `Sentry.init()`. **Logs** and **Application Metrics** need no extra configuration, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing**. + + + Call `Sentry.init()` before creating your Elysia app, then wrap the app with `Sentry.withElysia()` before defining routes. +The snippet also turns on: + +- Tracing: via `tracesSampleRate` + +Don't need a feature? Remove its integration and options from the snippet. + ```javascript {tabTitle:Bun} {mdExpandTabs} {filename: index.ts} import * as Sentry from "@sentry/elysia"; import { Elysia } from "elysia"; Sentry.init({ dsn: "___PUBLIC_DSN___", - // ___PRODUCT_OPTION_START___ performance - - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for tracing. - // We recommend adjusting this value in production - // Learn more at - // https://docs.sentry.io/platforms/javascript/guides/elysia/configuration/options/#tracesSampleRate + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance }); // withElysia returns the app instance, so you can chain routes directly @@ -90,15 +88,10 @@ import { node } from "@elysiajs/node"; Sentry.init({ dsn: "___PUBLIC_DSN___", - // ___PRODUCT_OPTION_START___ performance - - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for tracing. - // We recommend adjusting this value in production - // Learn more at - // https://docs.sentry.io/platforms/javascript/guides/elysia/configuration/options/#tracesSampleRate + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance }); // withElysia returns the app instance, so you can chain routes directly @@ -107,7 +100,7 @@ const app = Sentry.withElysia(new Elysia({ adapter: node() })) .listen(3000); ``` -### Customize Automatic Error Capturing (Optional) +### Customize Automatic Error Capturing The SDK captures 5xx errors automatically via a global `onError` hook. Client errors (3xx/4xx) are not captured by default. You can customize which errors are captured using the `shouldHandleError` option. @@ -121,59 +114,36 @@ const app = Sentry.withElysia(new Elysia(), { }); ``` -### Add Readable Stack Traces With Source Maps (Optional) +### Add Readable Stack Traces With Source Maps -### Control the Data You Send to Sentry (Optional) +### Control the Data You Send to Sentry -## Verify Your Setup +## Send Logs -Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. + -### Issues +If you're already logging with `console` or Consola, you can capture those logs with our console integrations. -First, let's verify that Sentry captures errors and creates issues in your Sentry project. Add the following route to your app, which triggers an error that Sentry will capture: +## Send Application Metrics -```javascript -app.get("/debug-sentry", () => { - throw new Error("My first Sentry error!"); -}); -``` + - +## Verify Your Setup -### Tracing +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. -To test your tracing configuration, update the previous code snippet by starting a trace to measure the time it takes for the execution of your code: +Add a route to your app that throws an error: ```javascript -app.get("/debug-sentry", async () => { - await Sentry.startSpan( - { - op: "test", - name: "My First Test Transaction", - }, - async () => { - await new Promise((resolve) => setTimeout(resolve, 100)); - throw new Error("My first Sentry error!"); - } - ); +app.get("/debug-sentry", () => { + throw new Error("Sentry Test Error"); }); ``` - - - - - - - - - - ### View Captured Data in Sentry Finally, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). @@ -182,10 +152,10 @@ Finally, head over to your project on [Sentry.io](https://sentry.io/) to view th ## Next Steps +At this point, you should have integrated Sentry into your Elysia application. Here's what to explore next: + - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Learn how to manually capture errors -- Continue to customize your configuration -- Get familiar with [Sentry's product features](/product/) like tracing, insights, and alerts +- Set up Agent Tracing to monitor your AI systems diff --git a/docs/platforms/javascript/guides/ember/index.mdx b/docs/platforms/javascript/guides/ember/index.mdx index ba92dfd4ed7fa5..4a12916733b9e7 100644 --- a/docs/platforms/javascript/guides/ember/index.mdx +++ b/docs/platforms/javascript/guides/ember/index.mdx @@ -106,44 +106,13 @@ export default { initialize }; ## Send Logs -Use `Sentry.logger` to send logs at different levels, such as `info`, `warn`, or `error`. -You can pass any attributes you want and search or filter by them later. + -If you're already logging with `console` or [Consola](https://github.com/unjs/consola), you can capture those logs with our console integrations. - -See Set Up Logs for all available logging methods and the syntax for formatting messages. - -```javascript -Sentry.logger.info("User example action completed"); - -Sentry.logger.warn("Slow operation detected", { - operation: "data_fetch", - duration: 3500, -}); - -Sentry.logger.error("Validation failed", { - form_field: "email", - reason: "Invalid email", -}); -``` +If you're already logging with `console` or Consola, you can capture those logs with our console integrations. ## Send Application Metrics -Use `Sentry.metrics` to send counters, gauges, and distributions from your app to Sentry. -You can pass any attributes you want and search or filter by them later. - -See Set Up Metrics for all available metric types and configuration options. - -```javascript -Sentry.metrics.count("checkout.failed", 1); - -Sentry.metrics.gauge("time_since_refresh", 4, { unit: "hour" }); - -Sentry.metrics.distribution("api_latency", 187, { - unit: "millisecond", - attributes: { endpoint: "/api/orders" }, -}); -``` + ## Verify Your Setup @@ -185,7 +154,6 @@ Now, head over to your project on [Sentry.io](https://sentry.io) to view the col At this point, you should have integrated Sentry into your Ember application. Here's what to explore next: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Set up Agent Tracing to monitor your AI systems - Set up tunneling to avoid ad blockers from blocking Sentry events diff --git a/docs/platforms/javascript/guides/express/index.mdx b/docs/platforms/javascript/guides/express/index.mdx index c495ee6e41d748..059dcbfb2b7458 100644 --- a/docs/platforms/javascript/guides/express/index.mdx +++ b/docs/platforms/javascript/guides/express/index.mdx @@ -1,6 +1,6 @@ --- title: Express -description: "Learn how to manually set up Sentry in your Express app and capture your first errors." +description: "Learn how to manually set up Sentry in your Express app and capture your first events." sdk: sentry.javascript.node fallbackGuide: javascript.node categories: diff --git a/docs/platforms/javascript/guides/fastify/index.mdx b/docs/platforms/javascript/guides/fastify/index.mdx index d7aecbc64fde8a..8635ad6a086058 100644 --- a/docs/platforms/javascript/guides/fastify/index.mdx +++ b/docs/platforms/javascript/guides/fastify/index.mdx @@ -1,6 +1,6 @@ --- title: Fastify -description: "Learn how to manually set up Sentry in your Fastify app and capture your first errors." +description: "Learn how to manually set up Sentry in your Fastify app and capture your first events." sdk: sentry.javascript.node fallbackGuide: javascript.node categories: diff --git a/docs/platforms/javascript/guides/firebase/index.mdx b/docs/platforms/javascript/guides/firebase/index.mdx index 62a9a512564497..0f9e4c37744ae3 100644 --- a/docs/platforms/javascript/guides/firebase/index.mdx +++ b/docs/platforms/javascript/guides/firebase/index.mdx @@ -1,6 +1,6 @@ --- title: Cloud Functions for Firebase -description: Learn how to set up Sentry in your Cloud Functions for Firebase project and capture your first errors. +description: Learn how to set up Sentry in your Cloud Functions for Firebase project and capture your first events. sdk: sentry.javascript.node fallbackGuide: javascript.node categories: @@ -28,36 +28,10 @@ This integration is enabled by default, so you get automatic performance monitor ## Install -Choose the features you want to configure, and this guide will show you how: - - - - - ### Install the Sentry SDK Run the command for your preferred package manager to add the Sentry SDK to your Firebase Functions project: - - -```bash {tabTitle:npm} -npm install @sentry/node --save -``` - -```bash {tabTitle:yarn} -yarn add @sentry/node -``` - -```bash {tabTitle:pnpm} -pnpm add @sentry/node -``` - - - - - ```bash {tabTitle:npm} npm install @sentry/node @sentry/profiling-node --save ``` @@ -70,46 +44,41 @@ yarn add @sentry/node @sentry/profiling-node pnpm add @sentry/node @sentry/profiling-node ``` - - ## Configure +**Error Monitoring** starts working as soon as you call `Sentry.init()`. **Logs** and **Application Metrics** need no extra configuration, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing** and **Profiling**. + + + Create an initialization file (for example, `instrument.js`) that imports and initializes Sentry. +The snippet also turns on: + +- Tracing: via `tracesSampleRate` +- Profiling: via `profileSessionSampleRate`, `profileLifecycle`, and the profiling integration + +Don't need a feature? Remove its integration and options from the snippet. + ```javascript {filename:instrument.js} const Sentry = require("@sentry/node"); -// ___PRODUCT_OPTION_START___ profiling const { nodeProfilingIntegration } = require("@sentry/profiling-node"); -// ___PRODUCT_OPTION_END___ profiling Sentry.init({ dsn: "___PUBLIC_DSN___", - - // ___PRODUCT_OPTION_START___ profiling - integrations: [ - // Add our Profiling integration + // enables Profiling nodeProfilingIntegration(), ], - // ___PRODUCT_OPTION_END___ profiling - // ___PRODUCT_OPTION_START___ performance - - // Add Tracing by setting tracesSampleRate - // Set tracesSampleRate to 1.0 to capture 100% of transactions - // We recommend adjusting this value in production - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ profiling - // Enable profiling for a percentage of sessions - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#profileSessionSampleRate + // Enables Profiling for every session. profileSessionSampleRate: 1.0, - // Profile automatically while there's an active sampled span profileLifecycle: "trace", - // ___PRODUCT_OPTION_END___ profiling }); ``` @@ -142,68 +111,48 @@ exports.onUserCreated = onDocumentCreated("users/{userId}", async (event) => { }); ``` -### Add Readable Stack Traces With Source Maps (Optional) +### Add Readable Stack Traces With Source Maps -### Control the Data You Send to Sentry (Optional) +### Control the Data You Send to Sentry -## Verify Your Setup +## Send Logs -Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. + -### Issues +If you're already logging with another library, use an integration to capture those logs as Sentry Logs automatically: +- `consoleLoggingIntegration` for `console` calls +- Consola +- Pino -Add a test function that throws an error to verify Sentry is capturing errors: +## Send Application Metrics -```javascript {filename:index.js} -require("./instrument"); // Import Sentry initialization first -const { onRequest } = require("firebase-functions/https"); - -exports.testSentry = onRequest(async (request, response) => { - throw new Error("Sentry Test Error - This is intentional!"); -}); -``` + -Deploy your functions and trigger the test endpoint: +On Node.js, `nodeRuntimeMetricsIntegration` also collects runtime health metrics automatically. -```bash -firebase deploy --only functions -curl https://-.cloudfunctions.net/testSentry -``` - - +## Verify Your Setup -### Tracing +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. -Firebase Functions are automatically instrumented for tracing. You can also create custom spans: +Add a test function that throws an error, deploy your functions, and trigger the test endpoint: ```javascript {filename:index.js} require("./instrument"); -const Sentry = require("@sentry/node"); const { onRequest } = require("firebase-functions/https"); -exports.tracedFunction = onRequest(async (request, response) => { - await Sentry.startSpan({ op: "task", name: "My Custom Task" }, async () => { - // Simulate some work - await new Promise((resolve) => setTimeout(resolve, 100)); - }); - - response.send("Done!"); +exports.testSentry = onRequest(async () => { + throw new Error("Sentry Test Error"); }); ``` - - - - - - - - - +```bash +firebase deploy --only functions +curl https://-.cloudfunctions.net/testSentry +``` ### View Captured Data in Sentry @@ -213,14 +162,11 @@ Now, head over to your project on [Sentry.io](https://sentry.io/) to view the co ## Next Steps -At this point, you should have integrated Sentry into your Cloud Functions for Firebase project. - -Now's a good time to customize your setup and look into more advanced topics: +At this point, you should have integrated Sentry into your Cloud Functions for Firebase application. Here's what to explore next: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Continue to customize your configuration -- Learn how to manually capture errors -- Get familiar with [Sentry's product features](/product/) like tracing, insights, and alerts +- Set up Agent Tracing to monitor your AI systems +- Explore Tracing to learn how to inspect application performance diff --git a/docs/platforms/javascript/guides/gatsby/index.mdx b/docs/platforms/javascript/guides/gatsby/index.mdx index 1e077dfe392fd8..ec585fdbbe0d23 100644 --- a/docs/platforms/javascript/guides/gatsby/index.mdx +++ b/docs/platforms/javascript/guides/gatsby/index.mdx @@ -1,7 +1,7 @@ --- title: Gatsby sdk: "sentry.javascript.gatsby" -description: "Learn how to set up Sentry in your Gatsby application, capture your first errors and traces, and view them in Sentry." +description: "Learn how to set up Sentry in your Gatsby application and capture your first events." categories: - browser - browser-only @@ -19,7 +19,7 @@ Run the command for your preferred package manager to add the Sentry SDK to your -`@sentry/gatsby` is a wrapper around the `@sentry/react` package, with additional Gatsby-specific functionality. This means that you can import all methods available in the `@sentry/react` package from `@sentry/gatsby`. +`@sentry/gatsby` is a wrapper around the `@sentry/react` package, with additional Gatsby-specific functionality. You can import all methods available in `@sentry/react` from `@sentry/gatsby`. @@ -56,7 +56,7 @@ const config: GatsbyConfig = { plugins: [ // ... { - resolve: "@sentry/gatsby" + resolve: "@sentry/gatsby", }, ], }; @@ -66,131 +66,92 @@ export default config; ## Configure -Choose the features you want to configure, and this guide will show you how: - - +**Error Monitoring** starts working as soon as you call `Sentry.init()`. **Logs** and **Application Metrics** need no extra configuration, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing**, **Session Replay**, and **User Feedback**. -### Initialize the Sentry SDK +### Initialize the SDK + +Initialize Sentry as early as possible in your application. Create a `sentry.config.(js|ts)` file in your project root and add the following code. + +The snippet also turns on: + +- Tracing: via `browserTracingIntegration()` and `tracesSampleRate` +- Session Replay: via `replayIntegration()`, sampled with `replaysSessionSampleRate` and `replaysOnErrorSampleRate` +- User Feedback: via `feedbackIntegration()` -Initialize Sentry as early as possible in your application. For this, create a new file `sentry.config.(js|ts)` in your project root and add the following: +Don't need a feature? Remove its integration and options from the snippet. ```javascript {filename:sentry.config.(js|ts)} import * as Sentry from "@sentry/gatsby"; Sentry.init({ dsn: "___PUBLIC_DSN___", - integrations: [ - // ___PRODUCT_OPTION_START___ performance + // enables automatic instrumentation Sentry.browserTracingIntegration(), - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ session-replay + // enables Session Replay Sentry.replayIntegration(), - // ___PRODUCT_OPTION_END___ session-replay - // ___PRODUCT_OPTION_START___ user-feedback + // enables User Feedback Sentry.feedbackIntegration({ - // Additional SDK configuration goes in here, for example: + // Additional integration configuration goes in here colorScheme: "system", }), - // ___PRODUCT_OPTION_END___ user-feedback ], - // ___PRODUCT_OPTION_START___ performance - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for tracing. - // We recommend adjusting this value in production - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ session-replay - // Capture Replay for 10% of all sessions, + // Set trace propagation targets for your API requests + tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/], + + // Capture replays for 10% of all sessions, // plus for 100% of sessions with an error - // Learn more at - // https://docs.sentry.io/platforms/javascript/session-replay/configuration/#general-integration-configuration + // Requires Sentry.replayIntegration() replaysSessionSampleRate: 0.1, replaysOnErrorSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ session-replay }); ``` -### Add Readable Stack Traces With Source Maps (Optional) +### Add Readable Stack Traces With Source Maps -### Avoid Ad Blockers With Tunneling (Optional) - - - -### Control the Data You Send to Sentry (Optional) +### Control the Data You Send to Sentry -## Verify Your Setup - -Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. - -### Issues +## Send Logs -To verify that Sentry captures errors and creates issues in your Sentry project, add the following test button to one of your pages. + - - Then, open the page in a browser and click the button to trigger a frontend - error. - +If you're already logging with `console` or Consola, you can capture those logs with our console integrations. - +## Send Application Metrics -```javascript {filename:index.(jsx|tsx)} - -``` + - -### Tracing +## Verify Your Setup -To test your tracing configuration, update the previous code snippet and wrap the error in a custom span. +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. -Then, open the page in a browser and click the button to trigger a frontend error and trace. +Add a test button to one of your pages. Clicking it will trigger an error for Sentry to capture. ```javascript {filename:index.(jsx|tsx)} ``` - - - - - - - - - + ### View Captured Data in Sentry @@ -200,16 +161,14 @@ Now, head over to your project on [Sentry.io](https://sentry.io/) to view the co ## Next Steps -At this point, you should have integrated Sentry into your Gatsby application and should already be sending data to your Sentry project. - -Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are: +At this point, you should have integrated Sentry into your Gatsby application. Here's what to explore next: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Extend Sentry to your backend using one of our [SDKs](/) -- Continue to customize your configuration -- Learn how to manually capture errors +- Set up Agent Tracing to monitor your AI systems +- Set up tunneling to avoid ad blockers from blocking Sentry events + - Find various topics in Troubleshooting - [Get support](https://www.sentry.help/en/) diff --git a/docs/platforms/javascript/guides/gcp-functions/index.mdx b/docs/platforms/javascript/guides/gcp-functions/index.mdx index 614ddfa02ed63c..e75d73a0e3621c 100644 --- a/docs/platforms/javascript/guides/gcp-functions/index.mdx +++ b/docs/platforms/javascript/guides/gcp-functions/index.mdx @@ -1,6 +1,6 @@ --- title: Google Cloud Functions -description: "Learn how to manually set up Sentry in your Google Cloud Functions and capture your first errors." +description: "Learn how to manually set up Sentry in your Google Cloud Functions and capture your first events." sdk: sentry.javascript.google-cloud-serverless fallbackGuide: javascript.node categories: @@ -26,14 +26,6 @@ categories: ## Install -Choose the features you want to configure, and this guide will show you how: - - - - - ### Install the Sentry SDK Run the command for your preferred package manager to add the Sentry SDK to your application: @@ -42,98 +34,128 @@ Run the command for your preferred package manager to add the Sentry SDK to your ## Configure -Make sure to initialize Sentry at the top of your function code and wrap each function with the appropriate helper. Select the tab that matches the kind of function you're using (HTTP, Background, or CloudEvent): - - +**Error Monitoring** starts working as soon as you call `Sentry.init()`. **Logs** and **Application Metrics** need no extra configuration, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing** and **Profiling**. -### Add Readable Stack Traces With Source Maps (Optional) - - - -### Control the Data You Send to Sentry (Optional) + - +Make sure to initialize Sentry at the top of your function code and wrap each function with the appropriate helper. -## Verify Your Setup +The snippet also turns on: -Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. +- Tracing: via `tracesSampleRate` +- Profiling: via `profileSessionSampleRate`, `profileLifecycle`, and the profiling integration -### Issues +Don't need a feature? Remove its integration and options from the snippet. -Let's verify that Sentry captures errors and creates issues in your Sentry project. Add an intentional error in your function: +Select the tab that matches the kind of function you're using (HTTP, Background, or CloudEvent): ```javascript {tabTitle:Http functions} {mdExpandTabs} +const Sentry = require("@sentry/google-cloud-serverless"); +const { nodeProfilingIntegration } = require("@sentry/profiling-node"); + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + integrations: [ + // enables Profiling + nodeProfilingIntegration(), + ], + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. + tracesSampleRate: 1.0, + // Enables Profiling for every session. + profileSessionSampleRate: 1.0, + profileLifecycle: "trace", +}); + exports.helloHttp = Sentry.wrapHttpFunction((req, res) => { - throw new Error("Sentry Test Error - This is intentional!"); + throw new Error("oh, hello there!"); }); ``` ```javascript {tabTitle:Background functions} -exports.helloBackground = Sentry.wrapEventFunction( - (data, context, callback) => { - throw new Error("Sentry Test Error - This is intentional!"); - } -); +const Sentry = require("@sentry/google-cloud-serverless"); +const { nodeProfilingIntegration } = require("@sentry/profiling-node"); + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + integrations: [ + // enables Profiling + nodeProfilingIntegration(), + ], + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. + tracesSampleRate: 1.0, + // Enables Profiling for every session. + profileSessionSampleRate: 1.0, + profileLifecycle: "trace", +}); + +exports.helloEvents = Sentry.wrapEventFunction((data, context, callback) => { + throw new Error("oh, hello there!"); +}); ``` ```javascript {tabTitle:CloudEvent functions} +const Sentry = require("@sentry/google-cloud-serverless"); +const { nodeProfilingIntegration } = require("@sentry/profiling-node"); + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + integrations: [ + // enables Profiling + nodeProfilingIntegration(), + ], + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. + tracesSampleRate: 1.0, + // Enables Profiling for every session. + profileSessionSampleRate: 1.0, + profileLifecycle: "trace", +}); + exports.helloEvents = Sentry.wrapCloudEventFunction((context, callback) => { - throw new Error("Sentry Test Error - This is intentional!"); + throw new Error("oh, hello there!"); }); ``` - -### Tracing +### Add Readable Stack Traces With Source Maps + + -To test tracing, wrap your code in a span: +### Control the Data You Send to Sentry -```javascript {tabTitle:Http functions} {mdExpandTabs} -exports.helloHttp = Sentry.wrapHttpFunction(async (req, res) => { - await Sentry.startSpan( - { op: "test", name: "My First Test Transaction" }, - async () => { - // Simulate some work - await new Promise((resolve) => setTimeout(resolve, 100)); - } - ); - - res.status(200).send("Success!"); -}); -``` + -```javascript {tabTitle:Background functions} -exports.helloBackground = Sentry.wrapEventFunction(async (data, context) => { - await Sentry.startSpan( - { op: "test", name: "My First Test Transaction" }, - async () => { - // Simulate some work - await new Promise((resolve) => setTimeout(resolve, 100)); - } - ); -}); -``` +## Send Logs -```javascript {tabTitle:CloudEvent functions} -exports.helloEvent = Sentry.wrapCloudEventFunction(async (context) => { - await Sentry.startSpan( - { op: "test", name: "My First Test Transaction" }, - async () => { - // Simulate some work - await new Promise((resolve) => setTimeout(resolve, 100)); - } - ); -}); -``` + + +If you're already logging with another library, use an integration to capture those logs as Sentry Logs automatically: +- `consoleLoggingIntegration` for `console` calls +- Consola +- Pino + +## Send Application Metrics - + - +On Node.js, `nodeRuntimeMetricsIntegration` also collects runtime health metrics automatically. + +## Verify Your Setup - +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. - +Add an intentional error to a wrapped function, then invoke it to verify that Sentry captures the error: - +```javascript +exports.helloHttp = Sentry.wrapHttpFunction((req, res) => { + throw new Error("Sentry Test Error"); +}); +``` ### View Captured Data in Sentry @@ -143,14 +165,11 @@ Now, head over to your project on [Sentry.io](https://sentry.io/) to view the co ## Next Steps -At this point, you should have integrated Sentry into your Google Cloud Platform functions, which should already be sending data to your Sentry project. - -Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are: +At this point, you should have integrated Sentry into your Google Cloud Functions application. Here's what to explore next: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Continue to customize your configuration -- Learn how to manually capture errors -- Get familiar with [Sentry's product features](/product/) like tracing, insights, and alerts +- Set up Agent Tracing to monitor your AI systems +- Explore Tracing to learn how to inspect application performance diff --git a/docs/platforms/javascript/guides/hapi/index.mdx b/docs/platforms/javascript/guides/hapi/index.mdx index d7196e2d78d278..9c3a0926768808 100644 --- a/docs/platforms/javascript/guides/hapi/index.mdx +++ b/docs/platforms/javascript/guides/hapi/index.mdx @@ -1,6 +1,6 @@ --- title: Hapi -description: "Learn how to manually set up Sentry in your Hapi app and capture your first errors." +description: "Learn how to manually set up Sentry in your Hapi app and capture your first events." sdk: sentry.javascript.node fallbackGuide: javascript.node categories: diff --git a/docs/platforms/javascript/guides/hono/index.mdx b/docs/platforms/javascript/guides/hono/index.mdx index e6dc2483d43e72..6dde32ed42f7b6 100644 --- a/docs/platforms/javascript/guides/hono/index.mdx +++ b/docs/platforms/javascript/guides/hono/index.mdx @@ -1,6 +1,6 @@ --- title: Hono -description: "Learn how to set up Sentry in your Hono app and capture your first errors." +description: "Learn how to set up Sentry in your Hono app and capture your first events." sdk: sentry.javascript.hono fallbackGuide: javascript.node categories: @@ -26,14 +26,6 @@ The community middleware `@hono/sentry` has been deprecated in favor of `@sentry ## Install -Choose the features you want to configure, and this guide will show you how: - - - - - ### Install the Sentry SDK Install the `@sentry/hono` package: @@ -70,8 +62,6 @@ npm install @sentry/bun deno add npm:@sentry/deno ``` - - ### Install the Profiling Package (Node.js Only) Profiling is only available for the Node.js runtime. Install the `@sentry/profiling-node` package: @@ -88,10 +78,13 @@ yarn add @sentry/profiling-node pnpm add @sentry/profiling-node ``` - - ## Configure +**Error Monitoring** starts working as soon as you configure the `sentry()` middleware or call `Sentry.init()` for Node.js. **Logs** and **Application Metrics** need no extra configuration, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing** and **Profiling**. Profiling is available only when you use the Node.js runtime. + + + If you're deploying to Cloudflare Workers, set the `nodejs_compat` compatibility flag. The SDK needs `AsyncLocalStorage`, which requires this flag. @@ -112,38 +105,34 @@ compatibility_flags = ["nodejs_compat"] Node.js requires Sentry to initialize before your application loads so it can instrument third-party libraries (like database clients). Create a separate initialization file: +The snippet also turns on: + +- Tracing: via `tracesSampleRate` +- Profiling: via `profileSessionSampleRate`, `profileLifecycle`, and `nodeProfilingIntegration()` + +Don't need a feature? Remove its integration and options from the snippet. + ```typescript {filename:instrument.mjs} // IMPORTANT: import from `@sentry/hono/node`, not `@sentry/node` import * as Sentry from "@sentry/hono/node"; -// ___PRODUCT_OPTION_START___ profiling import { nodeProfilingIntegration } from "@sentry/profiling-node"; -// ___PRODUCT_OPTION_END___ profiling Sentry.init({ dsn: "___PUBLIC_DSN___", - // ___PRODUCT_OPTION_START___ profiling + integrations: [ + // enables Profiling + nodeProfilingIntegration(), + ], - integrations: [nodeProfilingIntegration()], - // ___PRODUCT_OPTION_END___ profiling - // ___PRODUCT_OPTION_START___ performance - - // Set tracesSampleRate to 1.0 to capture 100% - // of spans for tracing. - // We recommend adjusting this value in production - // Learn more at - // https://docs.sentry.io/platforms/javascript/guides/hono/configuration/options/#tracesSampleRate + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ profiling - // Enable profiling for a percentage of sessions - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#profileSessionSampleRate + // Enables Profiling for every session. profileSessionSampleRate: 1.0, - // Profile automatically while there's an active sampled span profileLifecycle: "trace", - // ___PRODUCT_OPTION_END___ profiling }); ``` @@ -165,6 +154,10 @@ Add the `sentry()` middleware as early as possible in your Hono app. Before continuing, make sure you've completed the runtime-specific steps above: **Cloudflare Workers** users need to enable Node.js compatibility, and **Node.js** users need to create the instrument file. Since Node.js initializes Sentry in that file, the middleware doesn't take any options. +For Cloudflare Workers, Bun, and Deno, the snippet also turns on: + +- Tracing: via `tracesSampleRate` + ```typescript {tabTitle:Cloudflare Workers} {filename:index.ts} {mdExpandTabs} import { Hono } from "hono"; import { sentry } from "@sentry/hono/cloudflare"; @@ -175,12 +168,10 @@ app.use( sentry(app, { dsn: "___PUBLIC_DSN___", - // ___PRODUCT_OPTION_START___ performance - - // Set tracesSampleRate to 1.0 to capture 100% - // of spans for tracing. + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance }) ); @@ -213,12 +204,10 @@ app.use( sentry(app, { dsn: "___PUBLIC_DSN___", - // ___PRODUCT_OPTION_START___ performance - - // Set tracesSampleRate to 1.0 to capture 100% - // of spans for tracing. + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance }) ); @@ -237,12 +226,10 @@ app.use( sentry(app, { dsn: "___PUBLIC_DSN___", - // ___PRODUCT_OPTION_START___ performance - - // Set tracesSampleRate to 1.0 to capture 100% - // of spans for tracing. + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance }) ); @@ -276,17 +263,42 @@ By default, Sentry captures exceptions from Hono's `onError` handler, excluding To control which errors are captured, use the `shouldHandleError` option. -### Add Readable Stack Traces With Source Maps (Optional) +### Add Readable Stack Traces With Source Maps -### Control the Data You Send to Sentry (Optional) +### Control the Data You Send to Sentry +## Send Logs + + + +If you're already logging with another library, use an integration to capture those logs as Sentry Logs automatically: +- Node.js and Bun: `consoleLoggingIntegration` for `console` calls, Consola, and Pino +- Deno and Cloudflare Workers: `consoleLoggingIntegration` for `console` calls + +## Send Application Metrics + + + +You can also collect runtime health metrics automatically with the following integrations: +- Node.js: `nodeRuntimeMetricsIntegration` +- Bun: [`bunRuntimeMetricsIntegration`](/platforms/javascript/guides/bun/configuration/integrations/bunruntimemetrics/) +- Deno: [`denoRuntimeMetricsIntegration`](/platforms/javascript/guides/deno/configuration/integrations/denoruntimemetrics/) + ## Verify Your Setup - +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. + +Add a test route to your Hono app that throws an error, then request `/debug-sentry` to trigger it: + +```typescript +app.get("/debug-sentry", () => { + throw new Error("Sentry Test Error"); +}); +``` ### View Captured Data in Sentry @@ -296,15 +308,11 @@ Now, head over to your project on [Sentry.io](https://sentry.io/) to view the co ## Next Steps -At this point, you should have Sentry integrated into your Hono application and already be sending data to your Sentry project. - -Now's a good time to customize your setup and look into more advanced topics: +At this point, you should have integrated Sentry into your Hono application. Here's what to explore next: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Learn how to manually capture errors +- Set up Agent Tracing to monitor your AI systems - Explore Hono-specific features like custom error filtering -- Continue to customize your configuration -- Get familiar with [Sentry's product features](/product/) like tracing, insights, and alerts diff --git a/docs/platforms/javascript/guides/koa/index.mdx b/docs/platforms/javascript/guides/koa/index.mdx index f8c201fc2708ab..61f9b6d2450cbc 100644 --- a/docs/platforms/javascript/guides/koa/index.mdx +++ b/docs/platforms/javascript/guides/koa/index.mdx @@ -1,6 +1,6 @@ --- title: Koa -description: "Learn how to manually set up Sentry in your Koa app and capture your first errors." +description: "Learn how to manually set up Sentry in your Koa app and capture your first events." sdk: sentry.javascript.node fallbackGuide: javascript.node categories: diff --git a/docs/platforms/javascript/guides/nestjs/features/async-context.mdx b/docs/platforms/javascript/guides/nestjs/features/async-context.mdx index 44c5938deaff86..efe99e8323275e 100644 --- a/docs/platforms/javascript/guides/nestjs/features/async-context.mdx +++ b/docs/platforms/javascript/guides/nestjs/features/async-context.mdx @@ -3,30 +3,44 @@ title: Isolate Background Job Scopes description: "Learn how to isolate Sentry scopes in NestJS background jobs to prevent breadcrumb leakage into HTTP request events." --- -In NestJS, background job handlers like `@Cron()`, `@Interval()`, `@OnEvent()`, or BullMQ `@Processor()` handlers share the default isolation scope with incoming HTTP requests. This means breadcrumbs and tags added inside background jobs can leak into error events from unrelated HTTP requests, making it harder to debug issues. +Background jobs need their own isolation scopes to prevent breadcrumbs and tags from leaking into unrelated HTTP request events. -To prevent this, wrap each background job handler with `Sentry.withIsolationScope()` to give it its own isolated scope. Here's an example using `@Cron()`: +## Automatic Isolation -```typescript +Sentry automatically forks an isolation scope for each invocation of: + +- `@Cron()`, `@Interval()`, and `@Timeout()` handlers from `@nestjs/schedule` +- `@OnEvent()` handlers from `@nestjs/event-emitter` +- The `process()` method of `@Processor()` classes from `@nestjs/bullmq` + +These handlers do not need a manual `Sentry.withIsolationScope()` wrapper. + +## Manual Isolation + +For other background tasks, wrap each handler with `Sentry.withIsolationScope()` to give it its own isolated scope. + +For example, BullMQ lifecycle event listeners such as `@OnWorkerEvent('completed')` can run outside the isolation scope created for `process()` and need their own wrapper: + +```typescript {filename: my.processor.ts} import * as Sentry from "@sentry/nestjs"; -import { Injectable } from "@nestjs/common"; -import { Cron, CronExpression } from "@nestjs/schedule"; - -@Injectable() -export class MyJobService { - @Cron(CronExpression.EVERY_HOUR) - handleCron() { - Sentry.withIsolationScope(() => { - // Breadcrumbs and tags added here won't leak into HTTP request events - Sentry.addBreadcrumb({ message: "Processing scheduled job" }); - this.doWork(); - }); +import { OnWorkerEvent, Processor, WorkerHost } from "@nestjs/bullmq"; +import { Job } from "bullmq"; + +@Processor("my-queue") +export class MyProcessor extends WorkerHost { + async process(job: Job) { + // Your job processing logic runs in an automatically isolated scope. } - private doWork() { - // your job logic + @OnWorkerEvent("completed") + onCompleted(job: Job) { + return Sentry.withIsolationScope(() => { + Sentry.addBreadcrumb({ + message: "Job completed", + data: { jobId: job.id }, + }); + // Your completion handler logic. + }); } } ``` - -Apply the same pattern to `@Interval()`, `@OnEvent()`, `@Processor()`, and any other background task that runs outside the context of a request lifecycle. diff --git a/docs/platforms/javascript/guides/nestjs/index.mdx b/docs/platforms/javascript/guides/nestjs/index.mdx index eb37fbc9c5b5b2..2b12390bc90f7f 100644 --- a/docs/platforms/javascript/guides/nestjs/index.mdx +++ b/docs/platforms/javascript/guides/nestjs/index.mdx @@ -1,6 +1,6 @@ --- title: Nest.js -description: "Learn how to set up Sentry in your Nest.js app and capture your first errors." +description: "Learn how to set up Sentry in your Nest.js app and capture your first events." sdk: sentry.javascript.nestjs fallbackGuide: javascript.node categories: @@ -16,14 +16,6 @@ categories: ## Install -Choose the features you want to configure, and this guide will show you how: - - - - - ### Install the Sentry SDK Run the command for your preferred package manager to add the Sentry SDK to your application: @@ -32,11 +24,42 @@ Run the command for your preferred package manager to add the Sentry SDK to your ## Configure +**Error Monitoring** starts working as soon as you call `Sentry.init()`. **Logs** and **Application Metrics** need no extra configuration, and you'll learn how to send them in steps [#5](#send-logs) and [#6](#send-application-metrics-). +This guide also enables **Tracing** and **Profiling**. + + + ### Initialize the Sentry SDK -To import and initialize Sentry, create a file named `instrument.ts` in the root directory of your project and add the following code: +To import and initialize Sentry, create a file named `instrument.ts` in the root directory of your project and add the code snippet shown below. + +The snippet also turns on: + +- Tracing: via `tracesSampleRate` +- Profiling: via `profileSessionSampleRate`, `profileLifecycle`, and the profiling integration - +Don't need a feature? Remove its integration and options from the snippet. + +```typescript {filename: instrument.ts} +import * as Sentry from "@sentry/nestjs"; +import { nodeProfilingIntegration } from "@sentry/profiling-node"; + +// Ensure to call this before requiring any other modules! +Sentry.init({ + dsn: "___PUBLIC_DSN___", + integrations: [ + // enables Profiling + nodeProfilingIntegration(), + ], + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. + tracesSampleRate: 1.0, + // Enables Profiling for every session. + profileSessionSampleRate: 1.0, + profileLifecycle: "trace", +}); +``` ### Apply Instrumentation to Your App @@ -76,8 +99,11 @@ import { AppService } from "./app.service"; }) export class AppModule {} ``` +### Control the Data You Send to Sentry + + -### Add Readable Stack Traces With Source Maps (Optional) +### Add Readable Stack Traces With Source Maps @@ -85,19 +111,34 @@ export class AppModule {} -## Isolate Async Context for Background Jobs (Optional) +## Isolate Async Context for Background Jobs -If your NestJS app uses background jobs (such as `@Cron()`, `@Interval()`, `@OnEvent()`, or BullMQ), breadcrumbs from those jobs can leak into unrelated HTTP request error events. Wrap your background job handlers with `Sentry.withIsolationScope()` to isolate them. See Isolate Background Job Scopes for details and code examples. +Sentry automatically isolates background jobs using `@Cron()`, `@Interval()`, `@Timeout()`, `@OnEvent()`, and BullMQ `@Processor()` handlers. For other background tasks, wrap your handlers with `Sentry.withIsolationScope()` to prevent breadcrumbs and tags from leaking into unrelated events. See Isolate Background Job Scopes for details and code examples. -## Control the Data You Send to Sentry (Optional) +## Send Logs - + + +If you're already logging with another library, use an integration to capture those logs as Sentry Logs automatically: +- `consoleLoggingIntegration` for `console` calls +- Consola +- Pino + +## Send Application Metrics + + + +On Node.js, `nodeRuntimeMetricsIntegration` also collects runtime health metrics automatically. ## Verify Your Setup Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. - +Add an intentional error to a NestJS route handler and make a request to it: + +```typescript +throw new Error("Sentry Test Error"); +``` ### View Captured Data in Sentry @@ -107,20 +148,14 @@ Now, head over to your project on [Sentry.io](https://sentry.io/) to view the co ## Next Steps -At this point, you should have integrated Sentry into your Nest.js application and should already be sending data to your Sentry project. - -Now's a good time to customize your setup and look into more advanced topics. -Our next recommended steps for you are: +At this point, you should have integrated Sentry into your Nest.js application. Here's what to explore next: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Set up Agent Tracing to monitor your AI systems - Extend Sentry to your frontend using one of our [frontend SDKs](/) -- Learn how to [manually capture errors](/platforms/javascript/guides/nestjs/usage/) -- Continue to [customize your configuration](/platforms/javascript/guides/nestjs/configuration/) -- Get familiar with [Sentry's product features](/product/) like tracing, insights, and alerts -- Check out alternative installation methods - Find various topics in Troubleshooting - [Get support](https://www.sentry.help/en/) diff --git a/docs/platforms/javascript/guides/nextjs/index.mdx b/docs/platforms/javascript/guides/nextjs/index.mdx index af4d15d83054be..d5a6b14c9e06d4 100644 --- a/docs/platforms/javascript/guides/nextjs/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/index.mdx @@ -1,6 +1,6 @@ --- title: "Next.js" -description: Learn how to set up and configure Sentry in your Next.js application using the installation wizard, capture your first errors, logs and traces and view them in Sentry. +description: Learn how to set up Sentry in your Next.js application using the installation wizard and capture your first events. sdk: sentry.javascript.nextjs categories: - browser @@ -11,60 +11,75 @@ categories: - + ## Install -Run the Sentry wizard to automatically configure Sentry in your Next.js application: +### Run the Installation Wizard + +Run the Sentry wizard to automatically install the SDK and configure Sentry in your Next.js application: ```bash npx @sentry/wizard@latest -i nextjs ``` -The wizard will prompt you to select features. Choose the ones you want to enable: - - +The wizard asks whether you want to enable **Tracing** and **Session Replay**, route browser requests through your server to avoid ad blockers, and create an example page. To match the configuration in this guide, answer **Yes** to each. Prefer to set things up yourself? Check out the [Manual Setup](/platforms/javascript/guides/nextjs/manual-setup/) guide. -## What the Wizard Created +## Configure + +**Error Monitoring** starts working as soon as you call `Sentry.init()`. **Logs** and **Application Metrics** need no extra configuration, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing**, **Session Replay**, and **User Feedback**. + + + +### Initialize the SDK -The wizard configured Sentry for all Next.js runtime environments and created files to test your setup. +Next.js runs code in different environments, so the wizard creates a separate initialization file for each in your project's root directory (or `src` folder): -### SDK Initialization +- `instrumentation-client.ts`: runs in the browser +- `sentry.server.config.ts`: runs in the Node.js runtime +- `sentry.edge.config.ts`: runs in the Edge runtime -Next.js runs code in different environments. The wizard creates separate initialization files for each: +Use the tabs in the code box below to view each file. -- **Client** (`instrumentation-client.ts`) — Runs in the browser -- **Server** (`sentry.server.config.ts`) — Runs in Node.js -- **Edge** (`sentry.edge.config.ts`) — Runs in edge runtimes +The snippets also turn on: + +- Tracing: via `tracesSampleRate` in all three files +- Session Replay: via `replayIntegration()`, sampled with `replaysSessionSampleRate` and `replaysOnErrorSampleRate` +- User Feedback: via `feedbackIntegration()`. The wizard doesn't add this integration, so add it to `instrumentation-client.ts` yourself. + +Don't need a feature? Remove its integration and options from the snippets. ```typescript {tabTitle:Client} {mdExpandTabs} {filename:instrumentation-client.ts} import * as Sentry from "@sentry/nextjs"; Sentry.init({ dsn: "___PUBLIC_DSN___", - - // ___PRODUCT_OPTION_START___ performance - tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1, - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ session-replay - replaysSessionSampleRate: 0.1, - replaysOnErrorSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ session-replay integrations: [ - // ___PRODUCT_OPTION_START___ session-replay + // enables Session Replay Sentry.replayIntegration(), - // ___PRODUCT_OPTION_END___ session-replay + // enables User Feedback + Sentry.feedbackIntegration({ + // Additional integration configuration goes in here + colorScheme: "system", + }), ], + + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. + tracesSampleRate: 1.0, + + // Capture replays for 10% of all sessions, + // plus for 100% of sessions with an error + // Requires Sentry.replayIntegration() + replaysSessionSampleRate: 0.1, + replaysOnErrorSampleRate: 1.0, }); +// Instruments client-side navigations export const onRouterTransitionStart = Sentry.captureRouterTransitionStart; ``` @@ -74,9 +89,10 @@ import * as Sentry from "@sentry/nextjs"; Sentry.init({ dsn: "___PUBLIC_DSN___", - // ___PRODUCT_OPTION_START___ performance - tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1, - // ___PRODUCT_OPTION_END___ performance + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. + tracesSampleRate: 1.0, }); ``` @@ -86,21 +102,16 @@ import * as Sentry from "@sentry/nextjs"; Sentry.init({ dsn: "___PUBLIC_DSN___", - // ___PRODUCT_OPTION_START___ performance - tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1, - // ___PRODUCT_OPTION_END___ performance + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. + tracesSampleRate: 1.0, }); ``` - - -The example above samples 100% of traces in development and 10% in production. Monitor your [usage stats](https://sentry.io/orgredirect/organizations/:orgslug/settings/stats/?dataCategory=spans) and adjust `tracesSampleRate` based on your traffic volume. Learn more about [sampling configuration](/platforms/javascript/guides/nextjs/configuration/sampling/). - - - -### Server-Side Registration +### Register the Server-Side Configuration -The `instrumentation.ts` file registers your server and edge configurations with Next.js. +The wizard creates a [Next.js instrumentation file](https://nextjs.org/docs/app/guides/instrumentation) named `instrumentation.ts`. It loads your server and edge configurations, and exports `onRequestError` to capture errors from Server Components, route handlers, and middleware. ```typescript {filename:instrumentation.ts} import * as Sentry from "@sentry/nextjs"; @@ -109,6 +120,7 @@ export async function register() { if (process.env.NEXT_RUNTIME === "nodejs") { await import("./sentry.server.config"); } + if (process.env.NEXT_RUNTIME === "edge") { await import("./sentry.edge.config"); } @@ -117,173 +129,129 @@ export async function register() { export const onRequestError = Sentry.captureRequestError; ``` -### Next.js Configuration +### Capture React Render Errors + +If you use the App Router, the wizard adds Sentry to `app/global-error.tsx` to capture React rendering errors. If you use the Pages Router, it adds Sentry to `pages/_error.tsx` instead. + + -Your `next.config.ts` is wrapped with `withSentryConfig` to enable source map uploads, tunneling (to avoid ad-blockers), and other build-time features. +### Apply Instrumentation to Your App + +The wizard wraps your Next.js configuration with `withSentryConfig`. This instruments your app at build time, uploads source maps, and, if you said yes in the wizard, routes browser requests to Sentry through your server to avoid ad blockers. ```typescript {filename:next.config.ts} +import type { NextConfig } from "next"; import { withSentryConfig } from "@sentry/nextjs/config"; +const nextConfig: NextConfig = { + // Your existing Next.js configuration +}; + export default withSentryConfig(nextConfig, { org: "___ORG_SLUG___", project: "___PROJECT_SLUG___", - // Upload source maps for readable stack traces - authToken: process.env.SENTRY_AUTH_TOKEN, - - // Route Sentry requests through your server (avoids ad-blockers) - tunnelRoute: "/sentry-tunnel", - + // Only print logs for uploading source maps in CI silent: !process.env.CI, -}); -``` -### Error Handling + // Upload a larger set of source maps for prettier stack traces (increases build time) + widenClientFileUpload: true, -The wizard creates `app/global-error.tsx` to capture React rendering errors in your App Router application. - -```tsx {filename:app/global-error.tsx} -"use client"; - -import * as Sentry from "@sentry/nextjs"; -import { useEffect } from "react"; - -export default function GlobalError({ - error, -}: { - error: Error & { digest?: string }; -}) { - useEffect(() => { - Sentry.captureException(error); - }, [error]); - - return ( - - -

    Something went wrong!

    - - - ); -} + // Route browser requests to Sentry through a Next.js rewrite to avoid ad blockers. + // This can increase your server load as well as your hosting bill. + tunnelRoute: "/monitoring", +}); ``` -### Source Maps +### Add Readable Stack Traces With Source Maps -The wizard creates `.env.sentry-build-plugin` with your auth token for source map uploads. This file is automatically added to `.gitignore`. +The wizard stores your auth token in `.env.sentry-build-plugin` and adds the file to `.gitignore`. The Sentry build plugin uses this token to upload source maps when you build your app locally. -For CI/CD, set the `SENTRY_AUTH_TOKEN` environment variable in your build system. +For CI/CD builds, set the `SENTRY_AUTH_TOKEN` environment variable in your build system instead. -```bash {tabTitle:Local Development} {filename:.env.sentry-build-plugin} -SENTRY_AUTH_TOKEN=sntrys_eyJ... -``` + -```bash {tabTitle:CI/CD} -# Set as environment variable in your CI/CD system -SENTRY_AUTH_TOKEN=sntrys_eyJ... +```bash {filename:.env.sentry-build-plugin} +SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___ ``` -### Example Page - -The wizard creates `/sentry-example-page` with a button that triggers a test error. Use this to verify your setup. - -``` -app/ -├── sentry-example-page/ -│ └── page.tsx # Test page with error button -└── api/ - └── sentry-example-api/ - └── route.ts # Test API route -``` - -## Control the Data You Send to Sentry (Optional) +### Control the Data You Send to Sentry -## Verify Your Setup - - - -The example page tests all your enabled features with a single action: - -1. Start your dev server: - -```bash -npm run dev -``` - -2. Visit [localhost:3000/sentry-example-page](http://localhost:3000/sentry-example-page) +## Send Logs -3. Click **"Throw Sample Error"** + -### Check Your Data in Sentry +If you're already logging with another library, use an integration to capture those logs as Sentry Logs automatically: -**Errors** — [Open Issues](https://sentry.io/orgredirect/organizations/:orgslug/issues/) +- `consoleLoggingIntegration` for `console` calls +- Consola +- Pino +- Winston -You should see "This is a test error" with a full stack trace pointing to your source code. +## Send Application Metrics - + -**Tracing** — [Open Traces](https://sentry.io/orgredirect/organizations/:orgslug/explore/traces/) +In the Node.js runtime, `nodeRuntimeMetricsIntegration` also collects runtime health metrics automatically. -You should see the page load trace and the button click span. Learn more about custom spans. - - +## Verify Your Setup - +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. -**Session Replay** — [Open Replays](https://sentry.io/orgredirect/organizations/:orgslug/replays/) +The wizard created an example page that sends a test error from both your frontend and your backend: -Watch a video-like recording of your session, including the moment the error occurred. Learn more about Session Replay configuration. +1. Start your development server: - + ```bash + npm run dev + ``` - +2. Open [localhost:3000/sentry-example-page](http://localhost:3000/sentry-example-page) in your browser. +3. Click **Throw Sample Error**. -**Logs** — [Open Logs](https://sentry.io/orgredirect/organizations/:orgslug/explore/logs/) +If you skipped the example page, add a test button to one of your pages instead. Clicking it will trigger an error for Sentry to capture. -See structured log entries from your application. You can send logs from anywhere: +```tsx {filename:app/page.tsx} +"use client"; -```typescript -Sentry.logger.info("User action", { userId: "123" }); -Sentry.logger.warn("Slow response", { duration: 5000 }); -Sentry.logger.error("Operation failed", { reason: "timeout" }); +export default function Page() { + return ( + + ); +} ``` -Learn more about Logs configuration. + - +### View Captured Data in Sentry -**Application Metrics** — [Open Metrics](https://sentry.io/orgredirect/organizations/:orgslug/explore/metrics/) +Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). -Track and analyze custom application metrics to understand trends and patterns in your app's performance and behavior over time: + -```typescript -Sentry.metrics.count("checkout.failed", 1); -Sentry.metrics.gauge("queue.depth", 42); -Sentry.metrics.distribution("api_latency", 187, { - unit: "millisecond", -}); -``` +## Next Steps + +At this point, you should have integrated Sentry into your Next.js application. Here's what to explore next: -Learn more about Application Metrics. +- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Set up Agent Tracing to monitor agents built with the Vercel AI SDK, LangChain, and more +- Set up tunneling to avoid ad blockers blocking Sentry events, if you didn't enable it in the wizard - + - If you encountered issues with our installation wizard, try [setting up Sentry manually](/platforms/javascript/guides/nextjs/manual-setup/) -- Check [Troubleshooting](/platforms/javascript/guides/nextjs/troubleshooting/) for common issues -- [Get support](https://sentry.io/support/) +- Find various topics in Troubleshooting +- [Get support](https://www.sentry.help/en/) -## Next Steps - -You've successfully integrated Sentry into your Next.js application! Here's what to explore next: - -- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- [Logs Integrations](/platforms/javascript/guides/nextjs/logs/#integrations) - Connect popular logging libraries like Pino, Winston, and Bunyan -- [Distributed Tracing](/platforms/javascript/guides/nextjs/tracing/distributed-tracing/) - Trace requests across services and microservices -- [Agent Tracing](/platforms/javascript/guides/nextjs/agent-tracing/) - Monitor agents built with Vercel AI SDK, LangChain, and more -- [Connect GitHub + Seer](/integrations/source-code-mgmt/github/#installing-github) - Enable AI-powered [root cause analysis](/product/ai-in-sentry/seer/) by connecting your GitHub repository -- [Configuration Options](/platforms/javascript/guides/nextjs/configuration/) - Explore extended SDK configuration options - -     + diff --git a/docs/platforms/javascript/guides/nextjs/manual-setup/index.mdx b/docs/platforms/javascript/guides/nextjs/manual-setup/index.mdx index 77d865a77fd746..f8abeb4a8cb597 100644 --- a/docs/platforms/javascript/guides/nextjs/manual-setup/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/manual-setup/index.mdx @@ -165,7 +165,7 @@ The example above samples 100% of traces in development and 10% in production. M ### Register Server-Side SDK -Create a [Next.js Instrumentation file](https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation) named `instrumentation.ts` in your project root (or `src` folder). This file imports your server and edge configurations and exports `onRequestError` to capture server-side errors. +Create a [Next.js Instrumentation file](https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation) named `instrumentation.ts` next to your `app` directory (in your project root, or in `src` if you use `src/app`). Next.js production builds don't pick it up from other folders. This file imports your server and edge configurations and exports `onRequestError` to capture server-side errors. The `onRequestError` hook requires `@sentry/nextjs` version `8.28.0` or higher diff --git a/docs/platforms/javascript/guides/nextjs/manual-setup/pages-router.mdx b/docs/platforms/javascript/guides/nextjs/manual-setup/pages-router.mdx index 2360bf58348f45..341ebbca7861e1 100644 --- a/docs/platforms/javascript/guides/nextjs/manual-setup/pages-router.mdx +++ b/docs/platforms/javascript/guides/nextjs/manual-setup/pages-router.mdx @@ -192,7 +192,7 @@ Monitor your [usage stats](https://sentry.io/orgredirect/organizations/:orgslug/ ### Register Server-Side SDK -Create a [Next.js Instrumentation file](https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation) named `instrumentation.ts` in your project root (or `src` folder) to load it at server startup. +Create a [Next.js Instrumentation file](https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation) named `instrumentation.ts` next to your `pages` directory (in your project root, or in `src` if you use `src/pages`) to load it at server startup. Next.js production builds don't pick it up from other folders. The `onRequestError` export is what captures server-side errors in the Pages Router, including errors thrown in API routes and `getServerSideProps`. diff --git a/docs/platforms/javascript/guides/nitro/index.mdx b/docs/platforms/javascript/guides/nitro/index.mdx index 9c6e727ddcfd71..35f5abe881f798 100644 --- a/docs/platforms/javascript/guides/nitro/index.mdx +++ b/docs/platforms/javascript/guides/nitro/index.mdx @@ -1,6 +1,6 @@ --- title: Nitro -description: Learn how to set up Sentry in your Nitro app to capture errors and monitor performance. +description: Learn how to set up Sentry in your Nitro app, capture your first events, and monitor performance. sdk: sentry.javascript.nitro fallbackGuide: javascript.node categories: @@ -20,20 +20,12 @@ You need: - A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) - A Nitro application (`3.0.260415-beta` or newer) -- Node.js 20.19.0+ +- Node.js `20.19.0+` ## Install -Choose the features you want to configure, and this guide will show you how: - - - - - ### Install the Sentry SDK Run the command for your preferred package manager to add the Sentry SDK to your application: @@ -50,8 +42,17 @@ yarn add @sentry/nitro pnpm add @sentry/nitro ``` + +The SDK is a wrapper around `@sentry/node` and re-exports its full API. All Node.js instrumentation from `@sentry/node` (HTTP clients, databases, etc.) works out of the box, and the Nitro-specific tracing channels add parameterized routes and middleware spans on top. + + ## Configure +**Error Monitoring** starts working as soon as you call `Sentry.init()`. **Logs** and **Application Metrics** need no extra configuration, and you'll learn how to send them in steps [#4](#send-logs) and [#5](#send-application-metrics-). +This guide also enables **Tracing**. + + + The Nitro SDK is configured in two places: a build-time wrapper that registers a Nitro module, and a runtime file that initializes the SDK before your server starts. ### Configure the Nitro Build @@ -112,20 +113,21 @@ SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___ Create an `instrument.mjs` file in your project root: +The snippet also turns on: + +- Tracing: via `tracesSampleRate` + +Don't need a feature? Remove its options from the snippet. + ```javascript {filename: instrument.mjs} import * as Sentry from "@sentry/nitro"; Sentry.init({ dsn: "___PUBLIC_DSN___", - // ___PRODUCT_OPTION_START___ performance - - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for tracing. - // We recommend adjusting this value in production - // Learn more at - // https://docs.sentry.io/platforms/javascript/guides/nitro/configuration/options/#tracesSampleRate + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance }); ``` @@ -147,67 +149,11 @@ Load the instrumentation file with Node's `--import` flag before any Nitro comma } ``` -### Control the Data You Send to Sentry (Optional) +### Control the Data You Send to Sentry -## Verify Your Setup - -Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. - -### Issues - -Add a test route that throws an error, then open `/debug-sentry` in your browser (or `curl` it) to trigger the error: - -```javascript {filename: server/routes/debug-sentry.ts} -import { defineHandler } from "nitro/h3"; - -export default defineHandler(() => { - throw new Error("My first Sentry error!"); -}); -``` - - - -### Tracing - -To verify tracing, add a handler that starts a manual span: - -```javascript {filename: server/routes/debug-sentry.ts} -import { defineHandler } from "nitro/h3"; -import * as Sentry from "@sentry/nitro"; - -export default defineHandler(async () => { - await Sentry.startSpan( - { - op: "test", - name: "My First Test Transaction", - }, - async () => { - await new Promise((resolve) => setTimeout(resolve, 100)); - throw new Error("My first Sentry error!"); - } - ); -}); -``` - - - - - - - - - - - -### View Captured Data in Sentry - -Finally, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). - - - -## Features +## Automatic Instrumentation ### Automatic Error Capturing @@ -250,16 +196,49 @@ export default defineHandler(() => { }); ``` -## Runtime Behavior -The SDK is a wrapper around `@sentry/node` and re-exports its full API. All Node.js instrumentation from `@sentry/node` (HTTP clients, databases, etc.) works out of the box, and the Nitro-specific tracing channels add parameterized routes and middleware spans on top. +## Send Logs + + + +If you're already logging with another library, use an integration to capture those logs as Sentry Logs automatically: +- `consoleLoggingIntegration` for `console` calls +- Consola +- Pino + +## Send Application Metrics + + + +On Node.js, `nodeRuntimeMetricsIntegration` also collects runtime health metrics automatically. + +## Verify Your Setup + +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. + +Add a test route that throws an error, then open `/debug-sentry` in your browser to trigger the error: + +```javascript {filename: server/routes/debug-sentry.ts} +import { defineHandler } from "nitro/h3"; + +export default defineHandler(() => { + throw new Error("Sentry Test Error"); +}); +``` + +### View Captured Data in Sentry + +Finally, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). + + ## Next Steps +At this point, you should have integrated Sentry into your Nitro application. Here's what to explore next: + - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Learn how to manually capture errors -- Continue to customize your configuration -- Get familiar with [Sentry's product features](/product/) like tracing, insights, and alerts +- Set up Agent Tracing to monitor your AI systems +- Explore Tracing to learn how to inspect application performance diff --git a/docs/platforms/javascript/guides/node/index.mdx b/docs/platforms/javascript/guides/node/index.mdx index 69db24d7d47bf9..989e9c79357978 100644 --- a/docs/platforms/javascript/guides/node/index.mdx +++ b/docs/platforms/javascript/guides/node/index.mdx @@ -1,6 +1,6 @@ --- title: Node.js -description: "Learn how to manually set up Sentry in your Node.js app and capture your first errors." +description: "Learn how to manually set up Sentry in your Node.js app and capture your first events." sdk: sentry.javascript.node categories: - server diff --git a/docs/platforms/javascript/guides/react-router/index.mdx b/docs/platforms/javascript/guides/react-router/index.mdx index 23739a6ab86c50..27fcb45648a807 100644 --- a/docs/platforms/javascript/guides/react-router/index.mdx +++ b/docs/platforms/javascript/guides/react-router/index.mdx @@ -1,6 +1,6 @@ --- title: React Router Framework -description: Learn how to set up and configure Sentry in your React Router application (v7.15+) using the installation wizard, capture your first errors, and view them in Sentry. +description: Learn how to set up and configure Sentry in your React Router application (v7.15+) using the installation wizard, capture your first events, and view them in Sentry. sdk: sentry.javascript.react-router categories: - browser @@ -28,162 +28,49 @@ If you're using React Router in data or declarative mode, follow the instruction + + -## Configure - -If you prefer to configure Sentry manually, here are the configuration files the wizard would create: -In addition to capturing errors, you can monitor interactions between multiple services or applications by [enabling tracing](/concepts/key-terms/tracing/). You can also get to the root of an error or performance issue faster, by watching a video-like reproduction of a user session with [session replay](/product/session-replay/web/). +## Control the Data You Send to Sentry -Select which Sentry features you'd like to install in addition to Error Monitoring to get the corresponding installation and configuration instructions below. + - +## Send Logs - + -### Client-Side Configuration - -The wizard creates a client configuration file that initializes the Sentry SDK in your browser. - -The configuration includes your DSN (Data Source Name), which connects your app to your Sentry project, and enables the features you selected during installation. - -```tsx {tabTitle:Client} {filename:entry.client.tsx} -import * as Sentry from "@sentry/react-router"; -import { startTransition, StrictMode } from "react"; -import { hydrateRoot } from "react-dom/client"; -import { HydratedRouter } from "react-router/dom"; - -Sentry.init({ - dsn: "___PUBLIC_DSN___", - - integrations: [ - // ___PRODUCT_OPTION_START___ performance - // Registers and configures the Tracing integration, - // which automatically instruments your application to monitor its - // performance, including custom React Router routing instrumentation - Sentry.reactRouterTracingIntegration(), - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ session-replay - // Registers the Replay integration, - // which automatically captures Session Replays - Sentry.replayIntegration(), - // ___PRODUCT_OPTION_END___ session-replay - // ___PRODUCT_OPTION_START___ user-feedback - Sentry.feedbackIntegration({ - // Additional SDK configuration goes in here, for example: - colorScheme: "system", - }), - // ___PRODUCT_OPTION_END___ user-feedback - ], - // ___PRODUCT_OPTION_START___ performance - - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for tracing. - // We recommend adjusting this value in production - // Learn more at - // https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/options/#traces-sample-rate - tracesSampleRate: 1.0, - - // Set `tracePropagationTargets` to declare which URL(s) should have trace propagation enabled - tracePropagationTargets: [/^\//, /^https:\/\/yourserver\.io\/api/], - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ session-replay - - // Capture Replay for 10% of all sessions, - // plus 100% of sessions with an error - // Learn more at - // https://docs.sentry.io/platforms/javascript/guides/react-router/session-replay/configuration/#general-integration-configuration - replaysSessionSampleRate: 0.1, - replaysOnErrorSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ session-replay -}); - -startTransition(() => { - hydrateRoot( - document, - - - - ); -}); -``` +If you already use `console`, capture those calls as Sentry Logs with `consoleLoggingIntegration`. +We also provide integrations for: +- Consola +- Pino -### Server-Side Configuration - -The wizard also creates a server configuration file for Node.js runtime. - -For more advanced configuration options or to set up Sentry manually, check out our [manual setup guide](/platforms/javascript/guides/react-router/manual-setup/). - -```js {tabTitle:Server} {filename:instrument.server.mjs} -import * as Sentry from "@sentry/react-router"; -// ___PRODUCT_OPTION_START___ profiling -import { nodeProfilingIntegration } from "@sentry/profiling-node"; -// ___PRODUCT_OPTION_END___ profiling - -Sentry.init({ - dsn: "___PUBLIC_DSN___", - - // ___PRODUCT_OPTION_START___ profiling - - // Add our Profiling integration - integrations: [nodeProfilingIntegration()], - // ___PRODUCT_OPTION_END___ profiling - // ___PRODUCT_OPTION_START___ performance - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for tracing. - // We recommend adjusting this value in production - // Learn more at - // https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/options/#tracesSampleRate - tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ profiling - // Enable profiling for a percentage of sessions - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#profileSessionSampleRate - profileSessionSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ profiling -}); -``` +## Send Application Metrics -### Control the Data You Send to Sentry (Optional) + - +On Node.js, `nodeRuntimeMetricsIntegration` also collects runtime health metrics automatically. ## Verify Your Setup -The `sentry init` command checks the integration files it creates or modifies before it finishes. To confirm runtime events are reaching Sentry, start your React Router app, exercise the parts of your app that should send events, and then check your Sentry project. - -If you used the React Router Framework Mode installation wizard instead, you can also verify your setup with the example page it creates: - -1. Open the example page `/sentry-example-page` in your browser. For most React Router applications, this will be at localhost. -2. Observe the example page with a button that triggers test errors. +The `sentry init` command checks the integration files it creates or modifies before it finishes. To confirm runtime events are reaching Sentry, add a test button to your app and click it: + +```tsx + +``` -Clicking the button triggers an error that Sentry captures for you. The example also demonstrates how to test performance tracing. - - - -If you used the React Router Framework Mode installation wizard, explore the example files' code in your project to understand what's happening after your button click. - - - - - ### View Captured Data in Sentry Now, head over to your project on [Sentry.io](https://sentry.io) to view the collected data (it takes a couple of moments for the data to appear). @@ -192,15 +79,11 @@ Now, head over to your project on [Sentry.io](https://sentry.io) to view the col ## Next Steps -At this point, you should have integrated Sentry into your React Router Framework application and should already be sending data to your Sentry project. - -Now's a good time to customize your setup and look into more advanced topics. -Our next recommended steps for you are: +At this point, you should have integrated Sentry into your React Router Framework application. Here's what to explore next: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Learn how to manually capture errors -- Continue to customize your configuration -- Get familiar with [Sentry's product features](/product/) like tracing, insights, and alerts +- Set up tunneling to avoid ad blockers blocking Sentry events +- Read the manual setup guide for advanced configuration diff --git a/docs/platforms/javascript/guides/react-router/manual-setup.mdx b/docs/platforms/javascript/guides/react-router/manual-setup.mdx index 37848cd2a98a08..aec0eda1e80641 100644 --- a/docs/platforms/javascript/guides/react-router/manual-setup.mdx +++ b/docs/platforms/javascript/guides/react-router/manual-setup.mdx @@ -1,7 +1,7 @@ --- title: "Manual Setup" sidebar_order: 1 -description: "Learn how to manually set up Sentry in your React Router app (v7.15+) and capture your first errors." +description: "Learn how to manually set up Sentry in your React Router app (v7.15+) and capture your first events." --- @@ -12,29 +12,8 @@ description: "Learn how to manually set up Sentry in your React Router app (v7.1 ## Install -Choose the features you want to configure, and this guide will show you how: - - - - - -### Install the Sentry SDK - Run the command for your preferred package manager to add the SDK package to your application: - - ```bash {tabTitle:npm} npm install @sentry/react-router @sentry/profiling-node ``` @@ -47,24 +26,13 @@ yarn add @sentry/react-router @sentry/profiling-node pnpm add @sentry/react-router @sentry/profiling-node ``` - - - - ```bash {tabTitle:npm} - npm install @sentry/react-router - ``` - -```bash {tabTitle:yarn} -yarn add @sentry/react-router -``` +## Configure -```bash {tabTitle:pnpm} -pnpm add @sentry/react-router -``` - +**Error Monitoring** starts working as soon as you call `Sentry.init()`. **Logs** and **Application Metrics** need no extra configuration, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing**, **Profiling**, **Session Replay**, and **User Feedback**. -## Configure + ### Expose Entry Point Files @@ -78,58 +46,54 @@ npx react-router reveal Initialize Sentry in your `entry.client.tsx` file. +The snippet also turns on: + +- Tracing: via `tracesSampleRate` and `reactRouterTracingIntegration()` +- Session Replay: via `replayIntegration()`, sampled with `replaysSessionSampleRate` and `replaysOnErrorSampleRate` +- User Feedback: via `feedbackIntegration()` + +Don't need a feature? Remove its integration and options from the snippet. + The `sentryOnError` handler integrates with React Router's [`onError` hook](https://reactrouter.com/how-to/error-reporting) to automatically capture and report client-side errors to Sentry. -```tsx {diff} {filename: entry.client.tsx} -+import * as Sentry from "@sentry/react-router"; - import { startTransition, StrictMode } from "react"; - import { hydrateRoot } from "react-dom/client"; - import { HydratedRouter } from "react-router/dom"; - -+Sentry.init({ -+ dsn: "___PUBLIC_DSN___", -+ -+ integrations: [ -+ // ___PRODUCT_OPTION_START___ performance -+ // Registers and configures the Tracing integration, -+ // which automatically instruments your application to monitor its -+ // performance, including custom React Router routing instrumentation -+ Sentry.reactRouterTracingIntegration(), -+ // ___PRODUCT_OPTION_END___ performance -+ // ___PRODUCT_OPTION_START___ session-replay -+ // Registers the Replay integration, -+ // which automatically captures Session Replays -+ Sentry.replayIntegration(), -+ // ___PRODUCT_OPTION_END___ session-replay -+ // ___PRODUCT_OPTION_START___ user-feedback -+ Sentry.feedbackIntegration({ -+ // Additional SDK configuration goes in here, for example: -+ colorScheme: "system", -+ }), -+ // ___PRODUCT_OPTION_END___ user-feedback -+ ], -+ // ___PRODUCT_OPTION_START___ performance -+ -+ // Set tracesSampleRate to 1.0 to capture 100% -+ // of transactions for tracing. -+ // We recommend adjusting this value in production -+ // Learn more at -+ // https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/options/#traces-sample-rate -+ tracesSampleRate: 1.0, -+ -+ // Set `tracePropagationTargets` to declare which URL(s) should have trace propagation enabled -+ tracePropagationTargets: [/^\//, /^https:\/\/yourserver\.io\/api/], -+ // ___PRODUCT_OPTION_END___ performance -+ // ___PRODUCT_OPTION_START___ session-replay -+ -+ // Capture Replay for 10% of all sessions, -+ // plus 100% of sessions with an error -+ // Learn more at -+ // https://docs.sentry.io/platforms/javascript/guides/react-router/session-replay/configuration/#general-integration-configuration -+ replaysSessionSampleRate: 0.1, -+ replaysOnErrorSampleRate: 1.0, -+ // ___PRODUCT_OPTION_END___ session-replay -+}); +```tsx {filename: entry.client.tsx} +import * as Sentry from "@sentry/react-router"; +import { startTransition, StrictMode } from "react"; +import { hydrateRoot } from "react-dom/client"; +import { HydratedRouter } from "react-router/dom"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + + integrations: [ + // Registers and configures the Tracing integration, + // which automatically instruments your application to monitor its + // performance, including custom React Router routing instrumentation + Sentry.reactRouterTracingIntegration(), + // Registers the Replay integration, + // which automatically captures Session Replays + Sentry.replayIntegration(), + // Registers the User Feedback integration + Sentry.feedbackIntegration({ + // Additional SDK configuration goes in here, for example: + colorScheme: "system", + }), + ], + + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. + tracesSampleRate: 1.0, + + // Set `tracePropagationTargets` to declare which URL(s) should have trace propagation enabled + tracePropagationTargets: [/^\//, /^https:\/\/yourserver\.io\/api/], + + // Capture replays for 10% of all sessions, + // plus for 100% of sessions with an error + // Requires Sentry.replayIntegration() + replaysSessionSampleRate: 0.1, + replaysOnErrorSampleRate: 1.0, +}); startTransition(() => { hydrateRoot( @@ -156,36 +120,30 @@ On unsupported Node versions, you'll only lose auto-instrumentation for lower-le -First, create a file called `instrument.server.mjs` in the root of your project to initialize Sentry: +First, create a file called `instrument.server.mjs` in the root of your project to initialize Sentry. + +The snippet also turns on: + +- Tracing: via `tracesSampleRate` +- Profiling: via `nodeProfilingIntegration()` and `profileSessionSampleRate` + +Don't need a feature? Remove its integration and options from the snippet. ```js {filename: instrument.server.mjs} import * as Sentry from "@sentry/react-router"; -// ___PRODUCT_OPTION_START___ profiling import { nodeProfilingIntegration } from "@sentry/profiling-node"; -// ___PRODUCT_OPTION_END___ profiling Sentry.init({ dsn: "___PUBLIC_DSN___", - - // ___PRODUCT_OPTION_START___ profiling - - // Add our Profiling integration + // Enables Profiling integrations: [nodeProfilingIntegration()], - // ___PRODUCT_OPTION_END___ profiling - // ___PRODUCT_OPTION_START___ performance - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for tracing. - // We recommend adjusting this value in production - // Learn more at - // https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/options/#tracesSampleRate + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ profiling - // Enable profiling for a percentage of sessions - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#profileSessionSampleRate + // Enables Profiling for all sessions. + // We recommend reducing this value in production. profileSessionSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ profiling }); ``` @@ -399,7 +357,7 @@ When you import the instrumentation file directly instead of using the `--import -### Add Readable Stack Traces With Source Maps (Optional) +### Add Readable Stack Traces With Source Maps The stack traces in your Sentry errors probably won't look like your actual code without unminifying them. To fix this, upload your source maps to Sentry. @@ -453,77 +411,41 @@ export default { } satisfies Config; ``` -### Avoid Ad Blockers With Tunneling (Optional) - - - -### Control the Data You Send to Sentry (Optional) +### Control the Data You Send to Sentry -## Verify Your Setup - -Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. - -### Issues - -To verify that Sentry captures errors and creates issues in your Sentry project, throw an error in a loader. - - - Then, open the route in your browser and you should trigger an error. - - - - -```tsx {filename: error.tsx} -import type { Route } from "./+types/example-page"; +## Send Logs -export async function loader() { - throw new Error("My first Sentry error!"); -} + -export default function ExamplePage() { - return
    Loading this page will throw an error
    ; -} -``` +If you already use `console`, capture those calls as Sentry Logs with `consoleLoggingIntegration`. +We also provide integrations for: +- Consola +- Pino - -### Tracing +## Send Application Metrics -To test your tracing configuration, update the previous code snippet by starting a trace to measure the time it takes for the execution of your code. + -Then, open the route in your browser. You should start a trace and trigger an error. +On Node.js, `nodeRuntimeMetricsIntegration` also collects runtime health metrics automatically. -```tsx {filename: error.tsx} -import * as Sentry from "@sentry/react-router"; -import type { Route } from "./+types/example-page"; - -export async function loader() { - return Sentry.startSpan( - { - op: "test", - name: "My First Test Transaction", - }, - () => { - throw new Error("My first Sentry error!"); - } - ); -} +## Verify Your Setup -export default function ExamplePage() { - return
    Loading this page will throw an error
    ; -} +The `sentry init` command checks the integration files it creates or modifies before it finishes. To confirm runtime events are reaching Sentry, add a test button to your app and click it: + +```tsx + ``` -     - - - - - - - - + ### View Captured Data in Sentry @@ -533,15 +455,11 @@ Now, head over to your project on [Sentry.io](https://sentry.io) to view the col ## Next Steps -At this point, you should have integrated Sentry into your React Router Framework application and should already be sending data to your Sentry project. - -Now's a good time to customize your setup and look into more advanced topics. -Our next recommended steps for you are: +At this point, you should have integrated Sentry into your React Router Framework application. Here's what to explore next: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Learn how to manually capture errors -- Continue to customize your configuration -- Get familiar with [Sentry's product features](/product/) like tracing, insights, and alerts +- Set up tunneling to avoid ad blockers blocking Sentry events +- Set up Agent Tracing to monitor your AI systems diff --git a/docs/platforms/javascript/guides/react/index.mdx b/docs/platforms/javascript/guides/react/index.mdx index 37adc2d8523216..f44073a9ba55a5 100644 --- a/docs/platforms/javascript/guides/react/index.mdx +++ b/docs/platforms/javascript/guides/react/index.mdx @@ -1,6 +1,6 @@ --- title: React -description: "Learn how to set up Sentry in your React application, capture your first errors and traces, and view them in Sentry." +description: "Learn how to set up Sentry in your React application and capture your first events." sdk: sentry.javascript.react categories: - browser @@ -23,11 +23,11 @@ This guide is for client-side React applications (SPAs) built with tools like Vi     - + ## Install -Install the Sentry SDK using your preferred package manager: +Run the command for your preferred package manager to add the Sentry SDK to your application: ```bash {tabTitle:npm} npm install @sentry/react --save @@ -43,68 +43,53 @@ pnpm add @sentry/react ## Configure -Choose the features you want to configure: - - +**Error Monitoring** starts working as soon as you call `Sentry.init()`. **Logs** and **Application Metrics** need no extra configuration, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing**, **Session Replay**, and **User Feedback**. -### Initialize the Sentry SDK +### Initialize the SDK + +Create a file in your project's root directory (for example, `instrument.js`) and add your Sentry configuration. Import this file **before** any other imports in your application entry point. + +The snippet also turns on: -Create a file in your project's root directory (e.g., `instrument.js`) and add your Sentry configuration. +- Tracing: via `browserTracingIntegration()` and `tracesSampleRate`; `tracePropagationTargets` controls which API requests receive trace headers +- Session Replay: via `replayIntegration()`, sampled with `replaysSessionSampleRate` and `replaysOnErrorSampleRate` +- User Feedback: via `feedbackIntegration()` -This file must be imported **before** any other imports in your application entry point. +Don't need a feature? Remove its integration and options from the snippet. ```javascript {filename:instrument.js} import * as Sentry from "@sentry/react"; Sentry.init({ dsn: "___PUBLIC_DSN___", - integrations: [ - // ___PRODUCT_OPTION_START___ performance - // If you're using react router, use the integration for your react router version instead. - // Learn more at - // https://docs.sentry.io/platforms/javascript/guides/react/configuration/integrations/react-router/ + // enables automatic instrumentation Sentry.browserTracingIntegration(), - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ session-replay + // enables Session Replay Sentry.replayIntegration(), - // ___PRODUCT_OPTION_END___ session-replay - // ___PRODUCT_OPTION_START___ user-feedback + // enables User Feedback Sentry.feedbackIntegration({ - // Additional SDK configuration goes in here, for example: + // Additional integration configuration goes in here colorScheme: "system", }), - // ___PRODUCT_OPTION_END___ user-feedback ], - // ___PRODUCT_OPTION_START___ performance - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for tracing. - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // Set `tracePropagationTargets` to control for which URLs trace propagation should be enabled + // Set trace propagation targets for your API requests tracePropagationTargets: [/^\//, /^https:\/\/yourserver\.io\/api/], - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ session-replay - // Capture Replay for 10% of all sessions, + // Capture replays for 10% of all sessions, // plus for 100% of sessions with an error - // Learn more at - // https://docs.sentry.io/platforms/javascript/session-replay/configuration/#general-integration-configuration + // Requires Sentry.replayIntegration() replaysSessionSampleRate: 0.1, replaysOnErrorSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ session-replay }); ``` @@ -113,7 +98,6 @@ Sentry.init({ Import your Sentry configuration as the **first import** in your application entry point, then render your app. ```javascript {filename:main.jsx} -// Sentry initialization should be imported first! import "./instrument"; import App from "./App"; import { createRoot } from "react-dom/client"; @@ -135,13 +119,13 @@ import * as Sentry from "@sentry/react"; const container = document.getElementById("app"); const root = createRoot(container, { - // Callback called when an error is thrown and not caught by an ErrorBoundary. + // Called when an error is thrown and not caught by an ErrorBoundary. onUncaughtError: Sentry.reactErrorHandler((error, errorInfo) => { console.warn("Uncaught error", error, errorInfo.componentStack); }), - // Callback called when React catches an error in an ErrorBoundary. + // Called when React catches an error in an ErrorBoundary. onCaughtError: Sentry.reactErrorHandler(), - // Callback called when React automatically recovers from errors. + // Called when React automatically recovers from errors. onRecoverableError: Sentry.reactErrorHandler(), }); root.render(); @@ -182,19 +166,17 @@ Run the Sentry wizard to configure source map uploads for your bundler: npx @sentry/wizard@latest -i sourcemaps ``` - - -### Set Up Routing (Optional) +### Set Up Routing If you're using client-side routing, configure Sentry to capture navigation events for better performance insights. -Select your router: - - [React Router v7](/platforms/javascript/guides/react/features/react-router/v7/) - [React Router v6](/platforms/javascript/guides/react/features/react-router/v6/) - [Older versions](/platforms/javascript/guides/react/features/react-router/) - [TanStack Router](/platforms/javascript/guides/react/features/tanstack-router/) +When using React Router, replace `browserTracingIntegration()` with the integration for your router version. For example: + ```javascript {filename:instrument.js} import React from "react"; import * as Sentry from "@sentry/react"; @@ -208,6 +190,7 @@ import { Sentry.init({ dsn: "___PUBLIC_DSN___", integrations: [ + // enables automatic instrumentation for React Router v7 Sentry.reactRouterV7BrowserTracingIntegration({ useEffect: React.useEffect, useLocation, @@ -215,81 +198,59 @@ Sentry.init({ createRoutesFromChildren, matchRoutes, }), + // enables Session Replay + Sentry.replayIntegration(), + // enables User Feedback + Sentry.feedbackIntegration({ + colorScheme: "system", + }), ], -}); -``` - + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. + tracesSampleRate: 1.0, + tracePropagationTargets: [/^\\//, /^https:\\/\\/yourserver\\.io\\/api/], -### Capture Redux State Data (Optional) + // Capture replays for 10% of all sessions, + // plus for 100% of sessions with an error + // Requires Sentry.replayIntegration() + replaysSessionSampleRate: 0.1, + replaysOnErrorSampleRate: 1.0, +}); +``` -Capture Redux state and actions with your errors using `Sentry.createReduxEnhancer`. +### Capture Redux State Data -Learn more about [Redux integration options](/platforms/javascript/guides/react/features/redux/). +Capture Redux state and actions with your errors using `Sentry.createReduxEnhancer`. Learn more about [Redux integration options](/platforms/javascript/guides/react/features/redux/). ```javascript {filename:store.js} import { createStore, compose } from "redux"; import * as Sentry from "@sentry/react"; const sentryEnhancer = Sentry.createReduxEnhancer(); - const store = createStore(rootReducer, compose(sentryEnhancer)); ``` -### Avoid Ad Blockers With Tunneling (Optional) - -Some ad blockers prevent Sentry events from being sent. Use the `tunnel` option to route events through your server. - -Learn more about [setting up tunneling](/platforms/javascript/guides/react/troubleshooting/#using-the-tunnel-option). - -```javascript {filename:instrument.js} -Sentry.init({ - dsn: "___PUBLIC_DSN___", - tunnel: "/tunnel", -}); -``` - -### Control the Data You Send to Sentry (Optional) +### Control the Data You Send to Sentry -## Verify Your Setup - - - -Add a test button to trigger an error, then check Sentry to confirm it's working. - -**Errors** — [Open Issues](https://sentry.io/orgredirect/organizations/:orgslug/issues/) - -You should see "Sentry Test Error" with a stack trace pointing to your source code (if source maps are configured). - - - -**Tracing** — [Open Traces](https://sentry.io/orgredirect/organizations/:orgslug/explore/traces/) +## Send Logs -You should see page load traces and the test span. Learn more about custom instrumentation. + - +If you're already logging with `console` or Consola, you can capture those logs with our console integrations. - +## Send Application Metrics -**Session Replay** — [Open Replays](https://sentry.io/orgredirect/organizations/:orgslug/replays/) + -Watch a video-like recording of your session, including the moment the error occurred. Learn more about Session Replay configuration. - - - - - -**Logs** — [Open Logs](https://sentry.io/orgredirect/organizations/:orgslug/explore/logs/) - -See structured log entries from your application. Learn more about Logs configuration. - - +## Verify Your Setup -**Application Metrics** — [Open Metrics](https://sentry.io/orgredirect/organizations/:orgslug/explore/metrics/) +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. -Track and analyze custom application metrics to understand trends and patterns in your app's performance and behavior over time. Learn more about Application Metrics. +Add a test button to one of your components. Clicking it will trigger an error for Sentry to capture. ```javascript {filename:App.jsx} ``` - - -To test tracing, wrap the error in a span: - -```javascript - -``` - - - - - -Send logs from anywhere in your app: - -```javascript -Sentry.logger.info("User action", { userId: "123" }); -Sentry.logger.warn("Slow response", { duration: 5000 }); -Sentry.logger.error("Operation failed", { reason: "timeout" }); -``` - - + -Track metrics from anywhere in your app: +### View Captured Data in Sentry -```javascript -Sentry.metrics.count("checkout.failed", 1); -Sentry.metrics.gauge("queue.depth", 42); -Sentry.metrics.distribution("api_latency", 187, { - unit: "millisecond", -}); -``` +Now, head over to your project on [Sentry.io](https://sentry.io) to view the collected data (it takes a couple of moments for the data to appear). - + -**1. Enable debug mode** to see SDK activity in the console: - -```javascript {filename:instrument.js} -Sentry.init({ - dsn: "___PUBLIC_DSN___", - debug: true, -}); -``` +## Next Steps -**2. Check your DSN** — Ensure it's correctly copied from your [Sentry project settings](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/:projectId/keys/). +At this point, you should have integrated Sentry into your React application. Here's what to explore next: -**3. Disable ad blockers** — Some ad blockers prevent Sentry from sending events. See [tunneling](#avoid-ad-blockers-with-tunneling-optional) for a workaround. +- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Set up tunneling to avoid ad blockers from blocking Sentry events +- Explore React-specific features -**4. Check your quota** — View your [usage stats](https://sentry.io/orgredirect/organizations/:orgslug/stats/) to ensure you haven't exceeded your plan limits. + -For more help, see the Troubleshooting page. +- Find various topics in Troubleshooting +- [Get support](https://www.sentry.help/en/) -## Next Steps - -You've successfully integrated Sentry into your React application! Here's what to explore next: - -- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- [Session Replay](/platforms/javascript/guides/react/session-replay/) — Watch video-like reproductions of user sessions to debug errors in context -- [Distributed Tracing](/platforms/javascript/guides/react/tracing/distributed-tracing/) — Trace requests from your React frontend to backend services -- [Connect GitHub + Seer](/integrations/source-code-mgmt/github/#installing-github) — Enable AI-powered [root cause analysis](/product/ai-in-sentry/seer/) by connecting your repository -- [Logs](/platforms/javascript/guides/react/logs/) — Send structured logs correlated with errors and traces -- [Metrics](/platforms/javascript/guides/react/metrics/) — Track custom counters, gauges, and distributions to monitor application health - - + diff --git a/docs/platforms/javascript/guides/solid/index.mdx b/docs/platforms/javascript/guides/solid/index.mdx index edc1ad31136b12..4cfd9c1810a377 100644 --- a/docs/platforms/javascript/guides/solid/index.mdx +++ b/docs/platforms/javascript/guides/solid/index.mdx @@ -1,7 +1,7 @@ --- title: Solid sdk: sentry.javascript.solid -description: Learn how to manually set up Sentry in your Solid app and capture your first errors. +description: "Learn how to manually set up Sentry in your Solid app and capture your first events." categories: - browser - browser-only @@ -35,72 +35,59 @@ pnpm add @sentry/solid ## Configure -Choose the features you want to configure, and this guide will show you how: - - +**Error Monitoring** starts working as soon as you call `Sentry.init()`. **Logs** and **Application Metrics** need no extra configuration, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing**, **Session Replay**, and **User Feedback**. -### Initialize the Sentry SDK +### Initialize the SDK + +Initialize Sentry as early as possible in your application, for example, in your `index.(jsx|tsx)` file. + +The snippet also turns on: + +- Tracing: via `solidRouterBrowserTracingIntegration()` and `tracesSampleRate` +- Session Replay: via `replayIntegration()`, sampled with `replaysSessionSampleRate` and `replaysOnErrorSampleRate` +- User Feedback: via `feedbackIntegration()` -Initialize Sentry as early as possible in your application, for example, in your `index.(jsx|tsx)` file: +Don't need a feature? Remove its integration and options from the snippet. -```javascript {filename: index.jsx} +```javascript {filename:index.jsx} import * as Sentry from "@sentry/solid"; -// ___PRODUCT_OPTION_START___ performance import { solidRouterBrowserTracingIntegration } from "@sentry/solid/solidrouter"; -// ___PRODUCT_OPTION_END___ performance import { render } from "solid-js/web"; import { DEV } from "solid-js"; import App from "./app"; -// this will only initialize your Sentry client in production builds. +// Initialize Sentry only in production builds. if (!DEV) { Sentry.init({ dsn: "___PUBLIC_DSN___", - integrations: [ - // ___PRODUCT_OPTION_START___ performance + // enables automatic instrumentation for Solid Router solidRouterBrowserTracingIntegration(), - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ session-replay + // enables Session Replay Sentry.replayIntegration(), - // ___PRODUCT_OPTION_END___ session-replay - // ___PRODUCT_OPTION_START___ user-feedback + // enables User Feedback Sentry.feedbackIntegration({ - // Additional SDK configuration goes in here, for example: + // Additional integration configuration goes in here colorScheme: "system", }), - // ___PRODUCT_OPTION_END___ user-feedback ], - // ___PRODUCT_OPTION_START___ performance - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for tracing. - // We recommend adjusting this value in production - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // Set `tracePropagationTargets` to control for which URLs trace propagation should be enabled + // Set trace propagation targets for your API requests tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/], - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ session-replay - // Capture Replay for 10% of all sessions, - // plus 100% of sessions with an error - // Learn more at - // https://docs.sentry.io/platforms/javascript/session-replay/configuration/#general-integration-configuration + // Capture replays for 10% of all sessions, + // plus for 100% of sessions with an error + // Requires Sentry.replayIntegration() replaysSessionSampleRate: 0.1, replaysOnErrorSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ session-replay }); } @@ -117,75 +104,42 @@ To automatically report exceptions from inside a component tree to Sentry, wrap -### Add Readable Stack Traces With Source Maps (Optional) +### Add Readable Stack Traces With Source Maps -### Avoid Ad Blockers With Tunneling (Optional) - - - -### Control the Data You Send to Sentry (Optional) +### Control the Data You Send to Sentry -## Verify Your Setup - -Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. - -### Issues +## Send Logs -To verify that Sentry captures errors and creates issues in your Sentry project, add the following test button to one of your pages. + - - Then, open the page in a browser and click the button to trigger a frontend - error. - +If you're already logging with `console` or Consola, you can capture those logs with our console integrations. - +## Send Application Metrics -```javascript - -``` + - -### Tracing +## Verify Your Setup -To test your tracing configuration, update the previous code snippet to start a trace to measure the time it takes for the execution of your code. +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. -Then, open the page in a browser and click the button to trigger a frontend error and trace. +Add a test button to one of your components. Clicking it will trigger an error for Sentry to capture. ```javascript ``` - - - - - - - - - + ### View Captured Data in Sentry @@ -195,17 +149,14 @@ Now, head over to your project on [Sentry.io](https://sentry.io/) to view the co ## Next Steps -At this point, you should have integrated Sentry into your Solid application and should already be sending data to your Sentry project. - -Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are: +At this point, you should have integrated Sentry into your Solid application. Here's what to explore next: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Extend Sentry to your backend using one of our [SDKs](/) -- Continue to customize your configuration -- Make use of Solid-specific features -- Learn how to manually capture errors +- Set up tunneling to avoid ad blockers from blocking Sentry events +- Explore Solid-specific features + - Find various topics in Troubleshooting - [Get support](https://www.sentry.help/en/) diff --git a/docs/platforms/javascript/guides/solidstart/index.mdx b/docs/platforms/javascript/guides/solidstart/index.mdx index df59fca4df5dcc..f7c7a9f1baade9 100644 --- a/docs/platforms/javascript/guides/solidstart/index.mdx +++ b/docs/platforms/javascript/guides/solidstart/index.mdx @@ -1,6 +1,6 @@ --- title: SolidStart -description: Learn how to set up Sentry in your SolidStart application and capture your first errors. +description: Learn how to set up Sentry in your SolidStart application and capture your first events. sdk: sentry.javascript.solidstart categories: - browser @@ -24,19 +24,6 @@ This SDK is currently in **beta**. Beta features are still in progress and may h ## Install -Choose the features you want to configure, and this guide will show you how: - - - - - ### Install the Sentry SDK Run the command for your preferred package manager to add the Sentry SDK to your application: @@ -55,6 +42,11 @@ pnpm add @sentry/solidstart ## Configure +**Error Monitoring** starts working as soon as you call `Sentry.init()`. **Logs** and **Application Metrics** need no extra configuration, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing**, **Session Replay**, and **User Feedback**. + + + You need to initialize and configure the Sentry SDK in two places: the client side and the server side. @@ -65,57 +57,47 @@ The examples in this guide will use TypeScript with a `src` folder structure. Ma ### Configure Client-Side Sentry -Import and initialize the Sentry SDK in your `/src/entry-client.tsx` file. +Import and initialize the Sentry SDK in your `/src/entry-client.tsx` file. If you use Solid Router, add its tracing integration as shown below and wrap your router in the next step. + +The snippet also turns on: - - If you're using Solid Router, make sure to import and add the - `solidRouterBrowserTracingIntegration` to enable tracing in your app. - +- Tracing: via `tracesSampleRate` and `solidRouterBrowserTracingIntegration()` if you're using Solid Router +- Session Replay: via `replayIntegration()`, sampled with `replaysSessionSampleRate` and `replaysOnErrorSampleRate` +- User Feedback: via `feedbackIntegration()` + +Don't need a feature? Remove its integration and options from the snippet. ```jsx {filename:src/entry-client.tsx} import * as Sentry from "@sentry/solidstart"; -// ___PRODUCT_OPTION_START___ performance // import solidRouterBrowserTracingIntegration if you're using Solid Router import { solidRouterBrowserTracingIntegration } from "@sentry/solidstart/solidrouter"; -// ___PRODUCT_OPTION_END___ performance import { mount, StartClient } from "@solidjs/start/client"; Sentry.init({ dsn: "___PUBLIC_DSN___", integrations: [ - // ___PRODUCT_OPTION_START___ performance // add solidRouterBrowserTracingIntegration if you're using Solid Router + // enables automatic instrumentation solidRouterBrowserTracingIntegration(), - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ session-replay - // Replay may only be enabled for the client-side + // enables Session Replay Sentry.replayIntegration(), - // ___PRODUCT_OPTION_END___ session-replay - // ___PRODUCT_OPTION_START___ user-feedback + // enables User Feedback Sentry.feedbackIntegration({ - // Additional SDK configuration goes in here, for example: + // Additional integration configuration goes in here colorScheme: "system", }), - // ___PRODUCT_OPTION_END___ user-feedback ], - // ___PRODUCT_OPTION_START___ performance - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for tracing. - // We recommend adjusting this value in production - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ session-replay - // Capture Replay for 10% of all sessions, + // Capture replays for 10% of all sessions, // plus for 100% of sessions with an error - // Learn more at - // https://docs.sentry.io/platforms/javascript/session-replay/configuration/#general-integration-configuration + // Requires Sentry.replayIntegration() replaysSessionSampleRate: 0.1, replaysOnErrorSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ session-replay }); mount(() => , document.getElementById("app")); @@ -125,6 +107,10 @@ mount(() => , document.getElementById("app")); Initialize Sentry on the server. On SolidStart 2, do this in a Nitro startup plugin, which runs once when the server starts. On SolidStart 1, create an `instrument.server.ts` file in your `src` folder. +The snippet also turns on: + +- Tracing: via `tracesSampleRate` + ```typescript {tabTitle:SolidStart 2} {filename:server/plugins/sentry.ts} {mdExpandTabs} import * as Sentry from "@sentry/solidstart"; import { definePlugin } from "nitro"; @@ -132,15 +118,11 @@ import { definePlugin } from "nitro"; export default definePlugin(() => { Sentry.init({ dsn: "___PUBLIC_DSN___", - // ___PRODUCT_OPTION_START___ performance - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for tracing. - // We recommend adjusting this value in production - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance }); }); ``` @@ -150,15 +132,11 @@ import * as Sentry from "@sentry/solidstart"; Sentry.init({ dsn: "___PUBLIC_DSN___", - // ___PRODUCT_OPTION_START___ performance - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for tracing. - // We recommend adjusting this value in production - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance }); ``` @@ -218,8 +196,6 @@ export default defineConfig( ); ``` - - ### Configure Solid Router If you're using Solid Router and the Sentry `solidRouterBrowserTracingIntegration` integration, wrap your Solid Router with `withSentryRouterRouting` to enable Sentry to collect navigation spans: @@ -240,8 +216,6 @@ export default function App() { } ``` - - ### Run Your Application On SolidStart 2, the Vite plugin instruments your dependencies at build time, so the server needs no preload flag. Build with `vite build` and start the output directly. @@ -284,7 +258,7 @@ To automatically report exceptions from inside a component tree to Sentry, wrap -### Add Readable Stack Traces With Source Maps (Optional) +### Add Readable Stack Traces With Source Maps To upload source maps for clear error stack traces, add your Sentry auth token, organization, and project slug to the Sentry plugin in your build config: @@ -345,87 +319,44 @@ SENTRY_AUTH_TOKEN="___ORG_AUTH_TOKEN___" -### Avoid Ad Blockers With Tunneling (Optional) - - - -### Control the Data You Send to Sentry (Optional) +### Control the Data You Send to Sentry -## Verify Your Setup - -Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. +## Send Logs -### Issues + -To verify that Sentry captures errors and creates issues in your Sentry project, add a test button to an existing page or create a new one. +If you already use `console`, capture those calls as Sentry Logs with `consoleLoggingIntegration`. +We also provide integrations for: +- Consola +- Pino - - Then, open the page in a browser and click the button to trigger a frontend - error. - - - +## Send Application Metrics -```javascript - -``` + - -### Tracing +On Node.js, `nodeRuntimeMetricsIntegration` also collects runtime health metrics automatically. -To test tracing, create a test API route like `src/routes/sentry-test.tsx`: +## Verify Your Setup -```javascript {filename:sentry-test.tsx} -export async function GET() { - throw new Error("Sentry Example API Route Error"); -} -``` +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. -Next, update your test button to call this route and throw an error if the response isn't `ok`. +Add a test button to an existing page. Clicking it throws an error that Sentry captures: -Then, open the page in the browser and click the button to trigger a frontend error, an error in the API route, and a trace to measure the time it takes for the API request to complete. + -```javascript +```jsx ``` - - - - - - - - - - ### View Captured Data in Sentry Now, head over to your project on [Sentry.io](https://sentry.io) to view the collected data (it takes a couple of moments for the data to appear). @@ -434,15 +365,11 @@ Now, head over to your project on [Sentry.io](https://sentry.io) to view the col ## Next Steps -At this point, you should have integrated Sentry into your SolidStart application and should already be sending data to your Sentry project. - -Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are: +At this point, you should have integrated Sentry into your SolidStart application. Here's what to explore next: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Learn how to manually capture errors -- Continue to customize your configuration -- Learn how to make use of SolidStart-specific features -- Get familiar with [Sentry's product features](/) like tracing, insights, and alerts +- Set up Agent Tracing to monitor your AI systems +- Set up tunneling to avoid ad blockers blocking Sentry events diff --git a/docs/platforms/javascript/guides/svelte/index.mdx b/docs/platforms/javascript/guides/svelte/index.mdx index ec01e656bc2b60..1931db34362199 100644 --- a/docs/platforms/javascript/guides/svelte/index.mdx +++ b/docs/platforms/javascript/guides/svelte/index.mdx @@ -1,6 +1,6 @@ --- title: Svelte -description: "Learn how to manually set up Sentry in your Svelte app and capture your first errors." +description: "Learn how to manually set up Sentry in your Svelte app and capture your first events." sdk: sentry.javascript.svelte categories: - browser @@ -33,67 +33,56 @@ pnpm add @sentry/svelte ## Configure -Choose the features you want to configure, and this guide will show you how: - - +**Error Monitoring** starts working as soon as you call `Sentry.init()`. **Logs** and **Application Metrics** need no extra configuration, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing**, **Session Replay**, and **User Feedback**. -To use the SDK, initialize it in your Svelte entry point before bootstrapping your app. In a typical Svelte project, that is your `main.js` or `main.ts` file. +### Initialize the SDK + +Initialize the SDK in your Svelte entry point before bootstrapping your app. In a typical project, that is your `main.js` or `main.ts` file. + +The snippet also turns on: + +- Tracing: via `browserTracingIntegration()` and `tracesSampleRate` +- Session Replay: via `replayIntegration()`, sampled with `replaysSessionSampleRate` and `replaysOnErrorSampleRate` +- User Feedback: via `feedbackIntegration()` + +Don't need a feature? Remove its integration and options from the snippet. ```javascript {tabTitle: Svelte v5+} {mdExpandTabs} {filename: main.js} import { mount } from "svelte"; import "./app.css"; import App from "./App.svelte"; - import * as Sentry from "@sentry/svelte"; -// Initialize the Sentry SDK here Sentry.init({ dsn: "___PUBLIC_DSN___", - integrations: [ - // ___PRODUCT_OPTION_START___ performance + // enables automatic instrumentation Sentry.browserTracingIntegration(), - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ session-replay + // enables Session Replay Sentry.replayIntegration(), - // ___PRODUCT_OPTION_END___ session-replay - // ___PRODUCT_OPTION_START___ user-feedback + // enables User Feedback Sentry.feedbackIntegration({ - // Additional SDK configuration goes in here, for example: + // Additional integration configuration goes in here colorScheme: "system", }), - // ___PRODUCT_OPTION_END___ user-feedback ], - // ___PRODUCT_OPTION_START___ performance - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for tracing. - // We recommend adjusting this value in production - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // Set `tracePropagationTargets` to control for which URLs trace propagation should be enabled + // Set trace propagation targets for your API requests tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/], - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ session-replay - // Capture Replay for 10% of all sessions, - // plus 100% of sessions with an error - // Learn more at - // https://docs.sentry.io/platforms/javascript/session-replay/configuration/#general-integration-configuration + // Capture replays for 10% of all sessions, + // plus for 100% of sessions with an error + // Requires Sentry.replayIntegration() replaysSessionSampleRate: 0.1, replaysOnErrorSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ session-replay }); const app = mount(App, { @@ -106,47 +95,35 @@ export default app; ```javascript {tabTitle: Svelte v3-v4} {filename: main.js} import "./app.css"; import App from "./App.svelte"; - import * as Sentry from "@sentry/svelte"; -// Initialize the Sentry SDK here Sentry.init({ dsn: "___PUBLIC_DSN___", integrations: [ - // ___PRODUCT_OPTION_START___ performance + // enables Tracing Sentry.browserTracingIntegration(), - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ session-replay + // enables Session Replay Sentry.replayIntegration(), - // ___PRODUCT_OPTION_END___ session-replay - // ___PRODUCT_OPTION_START___ user-feedback + // enables User Feedback Sentry.feedbackIntegration({ - // Additional SDK configuration goes in here, for example: + // Additional integration configuration goes in here colorScheme: "system", }), - // ___PRODUCT_OPTION_END___ user-feedback ], - // ___PRODUCT_OPTION_START___ performance - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for tracing. - // We recommend adjusting this value in production - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // Set `tracePropagationTargets` to control for which URLs trace propagation should be enabled + // Set trace propagation targets for your API requests tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/], - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ session-replay - // Capture Replay for 10% of all sessions, - // plus 100% of sessions with an error - // Learn more at - // https://docs.sentry.io/platforms/javascript/session-replay/configuration/#general-integration-configuration + // Capture replays for 10% of all sessions, + // plus for 100% of sessions with an error + // Requires Sentry.replayIntegration() replaysSessionSampleRate: 0.1, replaysOnErrorSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ session-replay }); const app = new App({ @@ -156,31 +133,29 @@ const app = new App({ export default app; ``` -### Add Readable Stack Traces With Source Maps (Optional) +### Add Readable Stack Traces With Source Maps -### Avoid Ad Blockers With Tunneling (Optional) +### Control the Data You Send to Sentry - + -### Control the Data You Send to Sentry (Optional) +## Send Logs - + -## Verify Your Setup +If you're already logging with `console` or Consola, you can capture those logs with our console integrations. -Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. +## Send Application Metrics -### Issues + -To verify that Sentry captures errors and creates issues in your Sentry project, add the following test button to one of your pages, which will trigger an error that Sentry will capture when you click it. +## Verify Your Setup - - Open the page in a browser and click the button to trigger a frontend error. - +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. - +Add a test button to one of your components. Clicking it will trigger an error for Sentry to capture. ```jsx {tabTitle:Svelte v5+} {mdExpandTabs} {filename:SomeComponent.svelte} -``` - -```jsx {tabTitle:Svelte v3/v4} {filename:SomeComponent.svelte} - -``` - - - - - - - - - - + - ### View Captured Data in Sentry Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). @@ -260,15 +189,11 @@ Now, head over to your project on [Sentry.io](https://sentry.io/) to view the co ## Next Steps -At this point, you should have integrated Sentry into your Svelte application and should already be sending data to your Sentry project. - -Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are: +At this point, you should have integrated Sentry into your Svelte application. Here's what to explore next: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Extend Sentry to your backend using one of our [SDKs](/) -- Continue to customize your configuration -- Make use of Svelte-specific features -- Learn how to manually capture errors +- Set up tunneling to avoid ad blockers from blocking Sentry events +- Explore Svelte-specific features @@ -277,6 +202,4 @@ Now's a good time to customize your setup and look into more advanced topics. Ou - - diff --git a/docs/platforms/javascript/guides/vue/index.mdx b/docs/platforms/javascript/guides/vue/index.mdx index 0485d8531af7ac..fe85f766b38162 100644 --- a/docs/platforms/javascript/guides/vue/index.mdx +++ b/docs/platforms/javascript/guides/vue/index.mdx @@ -1,6 +1,6 @@ --- title: Vue -description: "Learn how to manually set up Sentry in your Vue app and capture your first errors." +description: "Learn how to manually set up Sentry in your Vue app and capture your first events." sdk: sentry.javascript.vue categories: - browser @@ -29,28 +29,30 @@ pnpm add @sentry/vue ## Configure -Choose the features you want to configure, and this guide will show you how: - - +**Error Monitoring** starts working as soon as you call `Sentry.init()`. **Logs** and **Application Metrics** need no extra configuration, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing**, **Session Replay**, and **User Feedback**. -To initialize Sentry in your Vue application, add the following code snippet to your `main.js`. +### Initialize the SDK + +To initialize Sentry in your Vue application, add the code shown below to your `main.js`. + +The snippet also turns on: + +- Tracing: via `browserTracingIntegration()` and `tracesSampleRate` +- Session Replay: via `replayIntegration()`, sampled with `replaysSessionSampleRate` and `replaysOnErrorSampleRate` +- User Feedback: via `feedbackIntegration()` + +Don't need a feature? Remove its integration and options from the snippet. -If you're creating more than one Vue 3 app within your application, check out how to initialize the SDK for [multiple apps](./features/multiple-apps/). +If you're creating more than one Vue 3 app within your application, see how to initialize the SDK for [multiple apps](./features/multiple-apps/). -```javascript {tabTitle:Vue 3} {filename:main.js} {3, 12-34} +```javascript {tabTitle:Vue 3} {filename:main.js} import { createApp } from "vue"; import { createRouter } from "vue-router"; import * as Sentry from "@sentry/vue"; @@ -65,49 +67,38 @@ const router = createRouter({ Sentry.init({ app, dsn: "___PUBLIC_DSN___", - integrations: [ - // ___PRODUCT_OPTION_START___ performance + // enables automatic instrumentation Sentry.browserTracingIntegration({ router }), - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ session-replay + // enables Session Replay Sentry.replayIntegration(), - // ___PRODUCT_OPTION_END___ session-replay - // ___PRODUCT_OPTION_START___ user-feedback + // enables User Feedback Sentry.feedbackIntegration({ - // Additional SDK configuration goes in here, for example: + // Additional integration configuration goes in here colorScheme: "system", }), - // ___PRODUCT_OPTION_END___ user-feedback ], - // ___PRODUCT_OPTION_START___ performance - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for tracing. - // We recommend adjusting this value in production - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // Set `tracePropagationTargets` to control for which URLs trace propagation should be enabled + // Set trace propagation targets for your API requests tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/], - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ session-replay - // Capture Replay for 10% of all sessions, + // Capture replays for 10% of all sessions, // plus for 100% of sessions with an error - // Learn more at - // https://docs.sentry.io/platforms/javascript/session-replay/configuration/#general-integration-configuration + // Requires Sentry.replayIntegration() replaysSessionSampleRate: 0.1, replaysOnErrorSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ session-replay }); app.use(router); app.mount("#app"); ``` -```javascript {tabTitle:Vue 2} {filename:main.js} {3, 11-35} +```javascript {tabTitle:Vue 2} {filename:main.js} import Vue from "vue"; import Router from "vue-router"; import * as Sentry from "@sentry/vue"; @@ -122,40 +113,30 @@ Sentry.init({ Vue, dsn: "___PUBLIC_DSN___", integrations: [ - // ___PRODUCT_OPTION_START___ performance + // enables Tracing Sentry.browserTracingIntegration({ router }), - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ session-replay + // enables Session Replay Sentry.replayIntegration(), - // ___PRODUCT_OPTION_END___ session-replay - // ___PRODUCT_OPTION_START___ user-feedback + // enables User Feedback Sentry.feedbackIntegration({ - // Additional SDK configuration goes in here, for example: + // Additional integration configuration goes in here colorScheme: "system", }), - // ___PRODUCT_OPTION_END___ user-feedback ], - // ___PRODUCT_OPTION_START___ performance - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for tracing. - // We recommend adjusting this value in production - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // Set `tracePropagationTargets` to control for which URLs trace propagation should be enabled + // Set trace propagation targets for your API requests tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/], - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ session-replay - // Capture Replay for 10% of all sessions, + // Capture replays for 10% of all sessions, // plus for 100% of sessions with an error - // Learn more at - // https://docs.sentry.io/platforms/javascript/session-replay/configuration/#general-integration-configuration + // Requires Sentry.replayIntegration() replaysSessionSampleRate: 0.1, replaysOnErrorSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ session-replay }); // ... @@ -166,17 +147,16 @@ new Vue({ }).$mount("#app"); ``` -### Configuration for Late-Defined Vue Apps +### Configure Late-Defined Vue Apps -If your Vue application is not defined from the start, you can add error monitoring for Vue-specific errors later on. -To manually add the integration for late-defined Vue applications, update your `main.js` file: +If your Vue application is not defined from the start, add error monitoring for Vue-specific errors later. To manually add the integration for a late-defined Vue application, update your `main.js` file: ```javascript {filename:main.js} import * as Sentry from "@sentry/vue"; Sentry.init({ dsn: "...", - // Filter out default `Vue` integration + // Filter out the default Vue integration integrations: (integrations) => integrations.filter((integration) => integration.name !== "Vue"), }); @@ -189,100 +169,57 @@ const app = createApp({ Sentry.addIntegration(Sentry.vueIntegration({ app })); ``` -### Configuration for Pinia - -To capture Pinia state data, use `Sentry.createSentryPiniaPlugin()` and add it to your Pinia store instance. +### Configure Pinia -Learn more about the [Pinia Plugin](./features/pinia/) and its options. +To capture Pinia state data, use `Sentry.createSentryPiniaPlugin()` and add it to your Pinia store instance. Learn more about the [Pinia Plugin](./features/pinia/) and its options. ```javascript import { createPinia } from "pinia"; import { createSentryPiniaPlugin } from "@sentry/vue"; const pinia = createPinia(); - pinia.use(createSentryPiniaPlugin()); ``` -### Add Readable Stack Traces With Source Maps (Optional) +### Add Readable Stack Traces With Source Maps -### Avoid Ad Blockers With Tunneling (Optional) - - - -### Control the Data You Send to Sentry (Optional) +### Control the Data You Send to Sentry -## Verify Your Setup - -Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. +## Send Logs -### Issues + -To verify that Sentry is capturing errors and creating issues in your Sentry project, add the following test button to one of your pages, which will trigger an error that Sentry will capture when you click it. +If you're already logging with `console` or Consola, you can capture those logs with our console integrations. - - Then, open the page in a browser and click the button to trigger a frontend - error. - - - - -```javascript {filename:App.vue} -// ... - -// ... +## Send Application Metrics -export default { - // ... - methods: { - throwError() { - throw new Error('Sentry Error'); - } - } -}; -``` + - -### Tracing +## Verify Your Setup -To test your tracing configuration, update the previous code snippet to start a performance trace to measure the time it takes for your code to execute. +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. -Then, open the page in a browser and click the button to trigger a frontend error and performance trace. +Add a test button to one of your pages. Clicking it will trigger an error for Sentry to capture. ```javascript {filename:App.vue} -// ... -// ... + ``` - - - - - - - - - + ### View Captured Data in Sentry @@ -292,15 +229,11 @@ Now, head over to your project on [Sentry.io](https://sentry.io/) to view the co ## Next Steps -At this point, you should have integrated Sentry into your Vue application and should already be sending data to your Sentry project. - -Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are: +At this point, you should have integrated Sentry into your Vue application. Here's what to explore next: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Extend Sentry to your backend using one of our [SDKs](/) -- Continue to customize your configuration -- Make use of Vue-specific features -- Learn how to manually capture errors +- Set up tunneling to avoid ad blockers from blocking Sentry events +- Explore Vue-specific features diff --git a/docs/platforms/javascript/guides/wasm/index.mdx b/docs/platforms/javascript/guides/wasm/index.mdx index 3514cc7d4182a8..a16cd93d5e3e8c 100644 --- a/docs/platforms/javascript/guides/wasm/index.mdx +++ b/docs/platforms/javascript/guides/wasm/index.mdx @@ -1,7 +1,7 @@ --- title: Wasm sdk: sentry.javascript.wasm -description: "Learn how to manually set up Sentry in your JavaScript application with WebAssembly modules and capture your first errors." +description: "Learn how to manually set up Sentry in your JavaScript application with WebAssembly modules and capture your first events." keywords: ["wasm", "webassembly"] categories: - browser @@ -21,14 +21,6 @@ categories: ## Install -Choose the features you want to configure, and this guide will show you how: - - - - - ### Install the Sentry SDK Run the command for your preferred package manager to add the Sentry SDK to your application: @@ -47,7 +39,18 @@ pnpm add @sentry/browser @sentry/wasm ## Configure -To use the SDK, initialize it in your application's entry point before loading your WebAssembly modules. Sentry's Wasm integration enhances the Browser SDK and allows it to provide more detailed debug information for WebAssembly modules, including Debug IDs, Debug Files, Code IDs, Code Files and memory addresses. +**Error Monitoring** starts working as soon as you call `Sentry.init()`. **Logs** and **Application Metrics** need no extra configuration, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing**. + + + +To use the SDK, initialize it in your application's entry point before loading your WebAssembly modules. Sentry's Wasm integration enhances the Browser SDK and adds debug information for WebAssembly modules. + +The snippet also turns on: + +- Tracing: via `tracesSampleRate` and `browserTracingIntegration()` + +Don't need a feature? Remove its integration and options from the snippet. ```javascript import * as Sentry from "@sentry/browser"; @@ -57,137 +60,49 @@ Sentry.init({ dsn: "___PUBLIC_DSN___", integrations: [ - // ___PRODUCT_OPTION_START___ performance + // enables automatic instrumentation Sentry.browserTracingIntegration(), - // ___PRODUCT_OPTION_END___ performance wasmIntegration(), ], - // ___PRODUCT_OPTION_START___ performance - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for tracing. - // We recommend adjusting this value in production - // Learn more at - // https://docs.sentry.io/platforms/javascript/guides/wasm/configuration/options/#tracesSampleRate + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, // Set `tracePropagationTargets` to control for which URLs trace propagation should be enabled tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/], - // ___PRODUCT_OPTION_END___ performance }); ``` -### Control the Data You Send to Sentry (Optional) +### Control the Data You Send to Sentry -## Verify Your Setup - -Let's test your setup and confirm that Sentry is working correctly and sending data from your WebAssembly modules to your Sentry project. - -### Issues +## Send Logs -To verify that Sentry captures errors from WebAssembly modules and creates issues in your Sentry project, add a function to your WebAssembly module that you can then call to cause an error (for example, division by zero). + -Here's what this could look like in Rust: +If you already use `console`, capture those calls as Sentry Logs with `consoleLoggingIntegration`. -```rust -#[no_mangle] -pub extern "C" fn divide(a: i32, b: i32) -> i32 { - // This will cause a division by zero trap when b is 0 - a / b -} -``` - -Then add a button to one of your app pages that, when pressed, calls the WebAssembly function to throw an error. Here's a simple HTML button: - - - -```html - -``` +## Send Application Metrics -Here's the JavaScript that calls the WebAssembly function. Make sure that you adjust it for your JavaScript framework. Note that, depending on how you compile modules, you can either call the function directly or access it through the WebAssembly API. + - - Open your app in the browser and click the button you just created to trigger - an error in your WebAssembly module. - - -```javascript -function testWasmError() { - try { - // Assuming you already have your WebAssembly module loaded as 'wasmModule' - // Replace this with your actual WebAssembly module instance - - // depending on how your module is compiled, call function directly - const result = wasmModule.divide(10, 0); - // or via WebAssembly API - //const result = wasmModule.instance.exports.divide(10, 0); - } catch (e) { - Sentry.captureException(e); - } -} -``` - - -### Tracing - -To test your tracing configuration, add a function to your WebAssembly module that does some calculations. Here's what it could look like in Rust: - -```rust -#[no_mangle] -pub extern "C" fn compute_intensive_function(iterations: i32) -> i32 { - // Add some computation to make tracing more visible - let mut sum = 0; - for i in 0..iterations * 1000 { - sum += i; - } - sum -} -``` - -Next, add a new button to your app: +## Verify Your Setup -```html - -``` +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. -Finally, create the JavaScript function that wraps your WebAssembly function calls in a Sentry span to measure the execution time. Again, make sure to adapt the code to fit your setup: +Call a WebAssembly function that triggers a trap, then capture the exception: ```javascript -function testWasmTracing() { - Sentry.startSpan({ op: "test", name: "Example Span" }, () => { - try { - // Assuming you already have your WebAssembly module loaded as 'wasmModule' - // Replace this with your actual WebAssembly module instance - - // depending on how your module is compiled, call function directly - const result = wasmModule.compute_intensive_function(1000); - // or via WebAssembly API - // const result = wasmModule.instance.exports.compute_intensive_function(1000); - console.log("Result:", result); - } catch (e) { - Sentry.captureException(e); - } - }); +try { + wasmModule.divide(10, 0); +} catch (error) { + Sentry.captureException(error); } ``` - - - - - - - - - - ### View Captured Data in Sentry Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). @@ -196,14 +111,9 @@ Now, head over to your project on [Sentry.io](https://sentry.io/) to view the co ## Next Steps -At this point, you should have integrated Sentry into your JavaScript application with WebAssembly modules and should already be sending data to your Sentry project. - -Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are: +At this point, you should have integrated Sentry into your JavaScript application with WebAssembly modules. Here's what to explore next: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Instrument your frontend and backend using our [SDKs](/) -- Continue to [customize your configuration](/platforms/javascript/guides/wasm/configuration/) -- Learn how to [manually capture errors](/platforms/javascript/guides/wasm/usage/) diff --git a/docs/platforms/kotlin/guides/kotlin-multiplatform/features/index.mdx b/docs/platforms/kotlin/guides/kotlin-multiplatform/features/index.mdx index b903e2c380e0ea..b72761c376248e 100644 --- a/docs/platforms/kotlin/guides/kotlin-multiplatform/features/index.mdx +++ b/docs/platforms/kotlin/guides/kotlin-multiplatform/features/index.mdx @@ -2,7 +2,7 @@ title: Features sidebar_order: 1 description: "Learn about the features of Sentry's Kotlin Multiplatform SDK." -sidebar_section: features +sidebar_hidden: true --- Sentry's Kotlin Multiplatform SDK enables automatic reporting of errors and exceptions. diff --git a/docs/platforms/php/common/configuration/options.mdx b/docs/platforms/php/common/configuration/options.mdx index 8e86d81a2f30fe..38299038c84159 100644 --- a/docs/platforms/php/common/configuration/options.mdx +++ b/docs/platforms/php/common/configuration/options.mdx @@ -215,9 +215,9 @@ The number of characters after which the values containing text in the event pay - + -This function is called with a breadcrumb object before the breadcrumb is added to the scope. When nothing is returned from the function, the breadcrumb is dropped. To pass the breadcrumb through, return the breadcrumb itself. +This function is called with a breadcrumb object before the breadcrumb is added to the scope. When `null` is returned from the function, the breadcrumb is dropped. To pass the breadcrumb through, return the breadcrumb itself. diff --git a/docs/platforms/php/common/troubleshooting/index.mdx b/docs/platforms/php/common/troubleshooting/index.mdx index 0782a7954ff7b6..6db5768463cf38 100644 --- a/docs/platforms/php/common/troubleshooting/index.mdx +++ b/docs/platforms/php/common/troubleshooting/index.mdx @@ -96,11 +96,7 @@ If you don't see any profiling data in [sentry.io](https://sentry.io), you can t - - - Currently, we only support crontab expressions with five fields. - - + diff --git a/docs/platforms/python/agent-tracing/anthropic/index.mdx b/docs/platforms/python/agent-tracing/anthropic/index.mdx index 0536774383c1fd..6055f79c34d59f 100644 --- a/docs/platforms/python/agent-tracing/anthropic/index.mdx +++ b/docs/platforms/python/agent-tracing/anthropic/index.mdx @@ -68,7 +68,19 @@ It may take a couple of moments for the data to appear in [sentry.io](https://se - The supported function is currently `messages.create` (both sync and async). -- Sentry considers LLM inputs/outputs as PII (Personally identifiable information) and doesn't include PII data by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False` as shown in the [Options section](#options) below. +- Sentry considers LLM inputs/outputs as PII (Personally identifiable information) and doesn't include prompts, messages, or responses by default. Tool definitions are still attached by default; setting `inputs` to `False` in the `gen_ai` key described below removes them. To include prompts, messages, and responses, use the `gen_ai` key of the `data_collection` option, which lets you control inputs and outputs separately. When you pass a `data_collection` dictionary, both are collected by default and `include_prompts` is ignored: + + ```python + sentry_sdk.init( + # ... + data_collection={ + # Record LLM inputs, but not outputs + "gen_ai": {"inputs": True, "outputs": False}, + }, + ) + ``` + + Alternatively, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False` as shown in the [Options section](#options) below. `send_default_pii` will be removed in version 3.0 of the SDK. ## Options @@ -95,7 +107,9 @@ You can pass the following keyword arguments to `AnthropicIntegration()`: - `include_prompts`: - Whether LLM inputs and outputs should be sent to Sentry. Sentry considers this data personal identifiable data (PII) by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False`. + Whether LLM inputs and outputs should be sent to Sentry. If you use the `data_collection` option, this option is ignored. Use the `gen_ai` key instead. + + Sentry considers this data personal identifiable data (PII) by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False`. `send_default_pii` will be removed in version 3.0 of the SDK. The default is `True`. diff --git a/docs/platforms/python/agent-tracing/google-genai/index.mdx b/docs/platforms/python/agent-tracing/google-genai/index.mdx index 2a9c185c599a1f..583db380806c62 100644 --- a/docs/platforms/python/agent-tracing/google-genai/index.mdx +++ b/docs/platforms/python/agent-tracing/google-genai/index.mdx @@ -37,9 +37,10 @@ sentry_sdk.init( # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. traces_sample_rate=1.0, - # Add data like inputs and responses; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "gen_ai": {"inputs": True, "outputs": True}, + }, integrations=[ GoogleGenAIIntegration(), ], @@ -81,7 +82,19 @@ It may take a couple of moments for the data to appear in [sentry.io](https://se - The supported function is currently `models.generate_content` (both sync and async). -- Sentry considers LLM inputs/outputs as PII (Personally identifiable information) and doesn't include PII data by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False` as shown in the [Options section](#options) below. +- Sentry considers LLM inputs/outputs as PII (Personally identifiable information) and doesn't include prompts, messages, or responses by default. Tool definitions and the tool calls returned by the model, including their arguments, are still attached by default; setting `inputs` and `outputs` to `False` in the `gen_ai` key described below removes them. The arguments and return values of Python functions you pass as tools are currently always attached to tool execution spans, regardless of these options. To include prompts, messages, and responses, use the `gen_ai` key of the `data_collection` option, which lets you control inputs and outputs separately. When you pass a `data_collection` dictionary, both are collected by default and `include_prompts` is ignored: + + ```python + sentry_sdk.init( + # ... + data_collection={ + # Record LLM inputs, but not outputs + "gen_ai": {"inputs": True, "outputs": False}, + }, + ) + ``` + + Alternatively, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False` as shown in the [Options section](#options) below. `send_default_pii` will be removed in version 3.0 of the SDK. ## Options @@ -108,7 +121,9 @@ You can pass the following keyword arguments to `GoogleGenAIIntegration()`: - `include_prompts`: - Whether LLM inputs and outputs should be sent to Sentry. Sentry considers this data personal identifiable data (PII) by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False`. + Whether LLM inputs and outputs should be sent to Sentry. If you use the `data_collection` option, this option is ignored. Use the `gen_ai` key instead. + + Sentry considers this data personal identifiable data (PII) by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False`. `send_default_pii` will be removed in version 3.0 of the SDK. The default is `True`. diff --git a/docs/platforms/python/agent-tracing/huggingface_hub/index.mdx b/docs/platforms/python/agent-tracing/huggingface_hub/index.mdx index 308b4522b23c8e..f48ab12ff42954 100644 --- a/docs/platforms/python/agent-tracing/huggingface_hub/index.mdx +++ b/docs/platforms/python/agent-tracing/huggingface_hub/index.mdx @@ -33,7 +33,10 @@ sentry_sdk.init( dsn="___PUBLIC_DSN___", environment="local", traces_sample_rate=1.0, - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "gen_ai": {"inputs": True, "outputs": True}, + }, ) ``` @@ -100,7 +103,19 @@ It may take a couple of moments for the data to appear in [sentry.io](https://se - All exceptions are reported. -- Sentry considers LLM and tokenizer inputs/outputs as PII (Personally identifiable information) and doesn't include PII data by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False` as shown in the [Options section](#options) below. +- Sentry considers LLM and tokenizer inputs/outputs as PII (Personally identifiable information) and doesn't include prompts, messages, or responses by default. Tool definitions are still attached by default; setting `inputs` to `False` in the `gen_ai` key described below removes them. To include prompts, messages, and responses, use the `gen_ai` key of the `data_collection` option, which lets you control inputs and outputs separately. When you pass a `data_collection` dictionary, both are collected by default and `include_prompts` is ignored: + + ```python + sentry_sdk.init( + # ... + data_collection={ + # Record LLM inputs, but not outputs + "gen_ai": {"inputs": True, "outputs": False}, + }, + ) + ``` + + Alternatively, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False` as shown in the [Options section](#options) below. `send_default_pii` will be removed in version 3.0 of the SDK. ## Options @@ -127,7 +142,9 @@ You can pass the following keyword arguments to `HuggingfaceHubIntegration()`: - `include_prompts` - Whether LLM and tokenizer inputs and outputs should be sent to Sentry. Sentry considers this data personal identifiable data (PII) by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False`. + Whether LLM and tokenizer inputs and outputs should be sent to Sentry. If you use the `data_collection` option, this option is ignored. Use the `gen_ai` key instead. + + Sentry considers this data personal identifiable data (PII) by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False`. `send_default_pii` will be removed in version 3.0 of the SDK. The default is `True`. diff --git a/docs/platforms/python/agent-tracing/index.mdx b/docs/platforms/python/agent-tracing/index.mdx index a983557512fd95..11dd15f3d36796 100644 --- a/docs/platforms/python/agent-tracing/index.mdx +++ b/docs/platforms/python/agent-tracing/index.mdx @@ -13,7 +13,7 @@ With Sentry Agent Tracing, you can ## Getting Started -Enable tracing. Supported AI libraries are instrumented automatically when their packages are installed. Prompt and response content is off by default — set `send_default_pii=True` to capture it (or configure `include_prompts` per integration). +Enable tracing. Supported AI libraries are instrumented automatically when their packages are installed. Prompt and response content is off by default — use the `gen_ai` key of the `data_collection` option to capture it. Alternatively, set `send_default_pii=True` (and configure `include_prompts` per integration). `send_default_pii` will be removed in version 3.0 of the SDK. ```python import sentry_sdk @@ -21,7 +21,10 @@ import sentry_sdk sentry_sdk.init( dsn="___PUBLIC_DSN___", traces_sample_rate=1.0, - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "gen_ai": {"inputs": True, "outputs": True}, + }, ) ``` @@ -73,7 +76,21 @@ Any of `id`, `email`, or `username` is sufficient — the Conversations tab disp ### Privacy Controls -LLM inputs and outputs are treated as PII and are **off** by default. Set `send_default_pii=True` to capture them. To keep other PII on but turn AI content off, set `include_prompts=False` on the integration: +LLM inputs and outputs are treated as PII and are **off** by default. Some integrations still attach tool data, such as tool definitions, by default. See each integration page for details. To capture them, use the `gen_ai` key of the `data_collection` option, which lets you control inputs and outputs separately. When you pass a `data_collection` dictionary, both are collected by default and `include_prompts` is ignored: + +```python +import sentry_sdk + +sentry_sdk.init( + dsn="___PUBLIC_DSN___", + data_collection={ + # Record LLM inputs, but not outputs + "gen_ai": {"inputs": True, "outputs": False}, + }, +) +``` + +Alternatively, set `send_default_pii=True` to capture them. To keep other PII on but turn AI content off, set `include_prompts=False` on the integration. `send_default_pii` will be removed in version 3.0 of the SDK. ```python import sentry_sdk diff --git a/docs/platforms/python/agent-tracing/langchain/index.mdx b/docs/platforms/python/agent-tracing/langchain/index.mdx index ef0a65978bfdea..2f3cf2a4d99eef 100644 --- a/docs/platforms/python/agent-tracing/langchain/index.mdx +++ b/docs/platforms/python/agent-tracing/langchain/index.mdx @@ -35,7 +35,10 @@ sentry_sdk.init( dsn="___PUBLIC_DSN___", environment="local", traces_sample_rate=1.0, - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "gen_ai": {"inputs": True, "outputs": True}, + }, debug=True, integrations=[ LangchainIntegration(), @@ -52,7 +55,10 @@ sentry_sdk.init( dsn="___PUBLIC_DSN___", environment="local", traces_sample_rate=1.0, - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "gen_ai": {"inputs": True, "outputs": True}, + }, debug=True, integrations=[ LangchainIntegration(), @@ -162,7 +168,19 @@ It may take a couple of moments for the data to appear in [sentry.io](https://se - All exceptions are reported. -- Sentry considers LLM and tokenizer inputs/outputs as PII (Personally identifiable information) and doesn't include PII data by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False` as shown in the [Options section](#options) below. +- Sentry considers LLM and tokenizer inputs/outputs as PII (Personally identifiable information) and doesn't include prompts, messages, or responses by default. Tool definitions, as well as tool calls passed in the model's invocation parameters, are still attached by default; setting `inputs` to `False` in the `gen_ai` key described below removes them. To include prompts, messages, and responses, use the `gen_ai` key of the `data_collection` option, which lets you control inputs and outputs separately. When you pass a `data_collection` dictionary, both are collected by default and `include_prompts` is ignored: + + ```python + sentry_sdk.init( + # ... + data_collection={ + # Record LLM inputs, but not outputs + "gen_ai": {"inputs": True, "outputs": False}, + }, + ) + ``` + + Alternatively, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False` as shown in the [Options section](#options) below. `send_default_pii` will be removed in version 3.0 of the SDK. ## Options @@ -189,7 +207,9 @@ You can pass the following keyword arguments to `LangchainIntegration()`: - `include_prompts` - Whether LLM and tokenizer inputs and outputs should be sent to Sentry. Sentry considers this data personal identifiable data (PII) by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False`. + Whether LLM and tokenizer inputs and outputs should be sent to Sentry. If you use the `data_collection` option, this option is ignored. Use the `gen_ai` key instead. + + Sentry considers this data personal identifiable data (PII) by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False`. `send_default_pii` will be removed in version 3.0 of the SDK. The default is `True`. diff --git a/docs/platforms/python/agent-tracing/langgraph/index.mdx b/docs/platforms/python/agent-tracing/langgraph/index.mdx index a9a2aa0f40174b..cbb16faaf5f0d7 100644 --- a/docs/platforms/python/agent-tracing/langgraph/index.mdx +++ b/docs/platforms/python/agent-tracing/langgraph/index.mdx @@ -33,7 +33,10 @@ sentry_sdk.init( dsn="___PUBLIC_DSN___", environment="local", traces_sample_rate=1.0, - send_default_pii=True + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "gen_ai": {"inputs": True, "outputs": True}, + }, ) ``` @@ -122,7 +125,9 @@ You can pass the following keyword arguments to `LanggraphIntegration()`: - `include_prompts` - Controls whether LLM inputs and outputs should be sent to Sentry. Sentry considers this data personal identifiable data (PII) by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False`. + Controls whether LLM inputs and outputs should be sent to Sentry. If you use the `data_collection` option, this option is ignored. Use the `gen_ai` key instead. + + Sentry considers this data personal identifiable data (PII) by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False`. `send_default_pii` will be removed in version 3.0 of the SDK. The default is `True`. diff --git a/docs/platforms/python/agent-tracing/litellm/index.mdx b/docs/platforms/python/agent-tracing/litellm/index.mdx index 3c110af96a172c..dde53bdd00c205 100644 --- a/docs/platforms/python/agent-tracing/litellm/index.mdx +++ b/docs/platforms/python/agent-tracing/litellm/index.mdx @@ -35,9 +35,10 @@ sentry_sdk.init( # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. traces_sample_rate=1.0, - # Add data like inputs and responses; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "gen_ai": {"inputs": True, "outputs": True}, + }, integrations=[ LiteLLMIntegration(), ], @@ -56,7 +57,10 @@ import litellm sentry_sdk.init( dsn="___PUBLIC_DSN___", traces_sample_rate=1.0, - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "gen_ai": {"inputs": True, "outputs": True}, + }, integrations=[ LiteLLMIntegration(), ], @@ -82,7 +86,19 @@ It may take a couple of moments for the data to appear in [sentry.io](https://se - The supported functions are currently `completion` and `embedding` (both sync and async). -- Sentry considers LLM inputs/outputs as PII (Personally identifiable information) and doesn't include PII data by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False` as shown in the [Options section](#options) below. +- Sentry considers LLM inputs/outputs as PII (Personally identifiable information) and doesn't include PII data by default. To include the data, use the `gen_ai` key of the `data_collection` option, which lets you control inputs and outputs separately. When you pass a `data_collection` dictionary, both are collected by default and `include_prompts` is ignored: + + ```python + sentry_sdk.init( + # ... + data_collection={ + # Record LLM inputs, but not outputs + "gen_ai": {"inputs": True, "outputs": False}, + }, + ) + ``` + + Alternatively, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False` as shown in the [Options section](#options) below. `send_default_pii` will be removed in version 3.0 of the SDK. ## Options @@ -109,7 +125,9 @@ You can pass the following keyword arguments to `LiteLLMIntegration()`: - `include_prompts`: - Whether LLM inputs and outputs should be sent to Sentry. Sentry considers this data personal identifiable data (PII) by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False`. + Whether LLM inputs and outputs should be sent to Sentry. If you use the `data_collection` option, this option is ignored. Use the `gen_ai` key instead. + + Sentry considers this data personal identifiable data (PII) by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False`. `send_default_pii` will be removed in version 3.0 of the SDK. The default is `True`. diff --git a/docs/platforms/python/agent-tracing/manual-instrumentation.mdx b/docs/platforms/python/agent-tracing/manual-instrumentation.mdx index 9845cdf3b80a3c..898cad3d59d44e 100644 --- a/docs/platforms/python/agent-tracing/manual-instrumentation.mdx +++ b/docs/platforms/python/agent-tracing/manual-instrumentation.mdx @@ -11,7 +11,7 @@ The [@sentry_sdk.trace()](/platforms/python/tracing/instrumentation/custom-instr This page describes the minimum span structure and attributes Sentry needs, then covers richer data such as messages, streaming metrics, and custom costs. -For conversations and privacy (`set_conversation_id`, `set_user`, `send_default_pii`), see the Agent Tracing guide. +For conversations and privacy (`set_conversation_id`, `set_user`, `data_collection`), see the Agent Tracing guide. ## Span Hierarchy @@ -46,7 +46,7 @@ To group turns into a [Conversation](/product/agents/conversations/), call `set_ Complex values (messages, tool definitions, arrays) must be **JSON strings** — span attributes only accept primitives. -Prompt, response, and tool content are treated as PII. They are only captured when `send_default_pii=True` (or per-integration `include_prompts`). See Privacy Controls. +Prompt, response, and tool content can contain PII. The SDK doesn't filter attributes you set manually, so the `data_collection` and `send_default_pii` options don't affect them. Decide what to record before you set these attributes. To learn how automatic integrations handle this data, see Privacy Controls. ## AI Request Span diff --git a/docs/platforms/python/agent-tracing/mistral/index.mdx b/docs/platforms/python/agent-tracing/mistral/index.mdx index 7f46f22e57aa44..29fee9feb9132c 100644 --- a/docs/platforms/python/agent-tracing/mistral/index.mdx +++ b/docs/platforms/python/agent-tracing/mistral/index.mdx @@ -35,9 +35,10 @@ sentry_sdk.init( # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. traces_sample_rate=1.0, - # Add data like inputs and responses; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "gen_ai": {"inputs": True, "outputs": True}, + }, integrations=[ MistralIntegration(), ], @@ -57,7 +58,10 @@ from mistralai.client import Mistral sentry_sdk.init( dsn="___PUBLIC_DSN___", traces_sample_rate=1.0, - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "gen_ai": {"inputs": True, "outputs": True}, + }, integrations=[ MistralIntegration(), ], @@ -87,7 +91,19 @@ It may take a couple of moments for the data to appear in [sentry.io](https://se - The supported functions are currently `Chat.complete` and `Chat.complete_async` (sync and async). Streaming completions (`stream=True`) are not instrumented. -- Sentry considers LLM inputs/outputs as PII (Personally identifiable information) and doesn't include PII data by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. +- Sentry considers LLM inputs/outputs as PII (Personally identifiable information) and doesn't include PII data by default. To include the data, use the `gen_ai` key of the `data_collection` option, which lets you control inputs and outputs separately. When you pass a `data_collection` dictionary, both are collected by default: + + ```python + sentry_sdk.init( + # ... + data_collection={ + # Record LLM inputs, but not outputs + "gen_ai": {"inputs": True, "outputs": False}, + }, + ) + ``` + + Alternatively, set `send_default_pii=True` in the `sentry_sdk.init()` call. `send_default_pii` will be removed in version 3.0 of the SDK. ## Supported Versions diff --git a/docs/platforms/python/agent-tracing/openai-agents/index.mdx b/docs/platforms/python/agent-tracing/openai-agents/index.mdx index 27eee283421429..4d3520779ae8ec 100644 --- a/docs/platforms/python/agent-tracing/openai-agents/index.mdx +++ b/docs/platforms/python/agent-tracing/openai-agents/index.mdx @@ -68,9 +68,10 @@ async def main() -> None: sentry_sdk.init( dsn="___PUBLIC_DSN___", traces_sample_rate=1.0, - # Add data like LLM and tool inputs/outputs; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "gen_ai": {"inputs": True, "outputs": True}, + }, ) await agents.Runner.run( @@ -93,7 +94,19 @@ Data on the following will be collected: - number of input and output tokens used - LLM models usage -Sentry considers LLM and tool inputs/outputs as PII and doesn't include PII data by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False` as shown in the [Options section](#options) below. +Sentry considers LLM and tool inputs/outputs as PII and doesn't include prompts, messages, or responses by default. Tool definitions are still attached by default; setting `inputs` to `False` in the `gen_ai` key described below removes them. To include prompts, messages, and responses, use the `gen_ai` key of the `data_collection` option, which lets you control inputs and outputs separately. When you pass a `data_collection` dictionary, both are collected by default and `include_prompts` is ignored: + +```python +sentry_sdk.init( + # ... + data_collection={ + # Record LLM and tool inputs, but not outputs + "gen_ai": {"inputs": True, "outputs": False}, + }, +) +``` + +Alternatively, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False` as shown in the [Options section](#options) below. `send_default_pii` will be removed in version 3.0 of the SDK. ## Options @@ -120,7 +133,9 @@ You can pass the following keyword arguments to `OpenAIAgentsIntegration()`: - `include_prompts`: - Whether LLM and tool inputs and outputs should be sent to Sentry. Sentry considers this data personal identifiable data (PII) by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False`. + Whether LLM and tool inputs and outputs should be sent to Sentry. If you use the `data_collection` option, this option is ignored. Use the `gen_ai` key instead. + + Sentry considers this data personal identifiable data (PII) by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False`. `send_default_pii` will be removed in version 3.0 of the SDK. The default is `True`. diff --git a/docs/platforms/python/agent-tracing/openai/index.mdx b/docs/platforms/python/agent-tracing/openai/index.mdx index 86d11124e77664..503ee0d30f9e0e 100644 --- a/docs/platforms/python/agent-tracing/openai/index.mdx +++ b/docs/platforms/python/agent-tracing/openai/index.mdx @@ -79,7 +79,19 @@ It may take a couple of moments for the data to appear in [sentry.io](https://se - The supported modules are currently `responses.create`, `chat.completions.create`, and `embeddings.create`. -- Sentry considers LLM and tokenizer inputs/outputs as PII (Personally identifiable information) and doesn't include PII data by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False` as shown in the [Options section](#options) below. +- Sentry considers LLM and tokenizer inputs/outputs as PII (Personally identifiable information) and doesn't include prompts, messages, or responses by default. Tool definitions are still attached by default; setting `inputs` to `False` in the `gen_ai` key described below removes them. To include prompts, messages, and responses, use the `gen_ai` key of the `data_collection` option, which lets you control inputs and outputs separately. When you pass a `data_collection` dictionary, both are collected by default and `include_prompts` is ignored: + + ```python + sentry_sdk.init( + # ... + data_collection={ + # Record LLM inputs, but not outputs + "gen_ai": {"inputs": True, "outputs": False}, + }, + ) + ``` + + Alternatively, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False` as shown in the [Options section](#options) below. `send_default_pii` will be removed in version 3.0 of the SDK. ## Options @@ -107,7 +119,9 @@ You can pass the following keyword arguments to `OpenAIIntegration()`: - `include_prompts`: - Whether LLM and tokenizer inputs and outputs should be sent to Sentry. Sentry considers this data personal identifiable data (PII) by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False`. + Whether LLM and tokenizer inputs and outputs should be sent to Sentry. If you use the `data_collection` option, this option is ignored. Use the `gen_ai` key instead. + + Sentry considers this data personal identifiable data (PII) by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False`. `send_default_pii` will be removed in version 3.0 of the SDK. The default is `True`. diff --git a/docs/platforms/python/agent-tracing/pydantic-ai/index.mdx b/docs/platforms/python/agent-tracing/pydantic-ai/index.mdx index 9289f13479102f..4e71bc19d5bdcc 100644 --- a/docs/platforms/python/agent-tracing/pydantic-ai/index.mdx +++ b/docs/platforms/python/agent-tracing/pydantic-ai/index.mdx @@ -41,9 +41,10 @@ from sentry_sdk.integrations.openai import OpenAIIntegration sentry_sdk.init( dsn="___PUBLIC_DSN___", traces_sample_rate=1.0, - # Add data like LLM and tool inputs/outputs; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "gen_ai": {"inputs": True, "outputs": True}, + }, integrations=[ PydanticAIIntegration(), ] @@ -57,9 +58,10 @@ from sentry_sdk.integrations.pydantic_ai import PydanticAIIntegration sentry_sdk.init( dsn="___PUBLIC_DSN___", traces_sample_rate=1.0, - # Add data like LLM and tool inputs/outputs; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "gen_ai": {"inputs": True, "outputs": True}, + }, integrations=[ PydanticAIIntegration(), ], @@ -118,9 +120,10 @@ async def main() -> None: sentry_sdk.init( dsn="___PUBLIC_DSN___", traces_sample_rate=1.0, - # Add data like LLM and tool inputs/outputs; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "gen_ai": {"inputs": True, "outputs": True}, + }, integrations=[ PydanticAIIntegration(), ] @@ -182,9 +185,10 @@ async def main() -> None: sentry_sdk.init( dsn="___PUBLIC_DSN___", traces_sample_rate=1.0, - # Add data like LLM and tool inputs/outputs; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "gen_ai": {"inputs": True, "outputs": True}, + }, integrations=[ PydanticAIIntegration(), ], @@ -211,7 +215,19 @@ Data on the following will be collected: - LLM models usage - model settings (temperature, max_tokens, etc.) -Sentry considers LLM and tool inputs/outputs as PII and doesn't include PII data by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False` as shown in the Options section below. +Sentry considers LLM and tool inputs/outputs as PII and doesn't include prompts, messages, or responses by default. Tool definitions are still attached by default; setting `inputs` to `False` in the `gen_ai` key described below removes them. To include prompts, messages, and responses, use the `gen_ai` key of the `data_collection` option, which lets you control inputs and outputs separately. When you pass a `data_collection` dictionary, both are collected by default and `include_prompts` is ignored: + +```python +sentry_sdk.init( + # ... + data_collection={ + # Record LLM and tool inputs, but not outputs + "gen_ai": {"inputs": True, "outputs": False}, + }, +) +``` + +Alternatively, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False` as shown in the Options section below. `send_default_pii` will be removed in version 3.0 of the SDK. ## Options @@ -238,7 +254,9 @@ You can pass the following keyword arguments to `PydanticAIIntegration()`: - `include_prompts`: - Whether LLM and tool inputs and outputs should be sent to Sentry. Sentry considers this data personal identifiable data (PII) by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False`. + Whether LLM and tool inputs and outputs should be sent to Sentry. If you use the `data_collection` option, this option is ignored. Use the `gen_ai` key instead. + + Sentry considers this data personal identifiable data (PII) by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False`. `send_default_pii` will be removed in version 3.0 of the SDK. The default is `True`. diff --git a/docs/platforms/python/agent-tracing/typesafe/index.mdx b/docs/platforms/python/agent-tracing/typesafe/index.mdx index 3082e80d4807bb..3d3b9c6ea7caf8 100644 --- a/docs/platforms/python/agent-tracing/typesafe/index.mdx +++ b/docs/platforms/python/agent-tracing/typesafe/index.mdx @@ -33,9 +33,10 @@ sentry_sdk.init( # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. traces_sample_rate=1.0, - # Add data like inputs and responses; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "gen_ai": {"inputs": True, "outputs": True}, + }, integrations=[ TypeSafeIntegration(), ], @@ -55,7 +56,10 @@ from typesafe_sdk import Choice, TypeSafeClient sentry_sdk.init( dsn="___PUBLIC_DSN___", traces_sample_rate=1.0, - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "gen_ai": {"inputs": True, "outputs": True}, + }, integrations=[ TypeSafeIntegration(), ], diff --git a/docs/platforms/python/configuration/options.mdx b/docs/platforms/python/configuration/options.mdx index 786f17fc595d2e..776a980fa12cab 100644 --- a/docs/platforms/python/configuration/options.mdx +++ b/docs/platforms/python/configuration/options.mdx @@ -102,7 +102,7 @@ If this flag is enabled, [certain personally identifiable information (PII)](/pl If you enable this option, be sure to manually remove what you don't want to send using our features for managing [_Sensitive Data_](../../data-management/sensitive-data/). - We plan to eventually deprecate `send_default_pii` in favor of the [`data_collection`](#data_collection) option, but that won't happen until a future major version. Until then, `send_default_pii` remains fully supported. + `send_default_pii` will be removed in version 3.0 of the SDK. Use the [`data_collection`](#data_collection) option instead. If you set both, `send_default_pii` is ignored entirely and the SDK emits a `DeprecationWarning`. @@ -203,8 +203,8 @@ This option can be overridden using `in_app_include`. This parameter controls whether integrations should capture HTTP request bodies. It can be set to one of the following values: - `never`: Request bodies are never sent. -- `small`: Only small request bodies will be captured. The cutoff for small depends on the SDK (typically 4KB). -- `medium`: Medium and small requests will be captured (typically 10KB). +- `small`: Only small request bodies (up to 1,000 bytes) will be captured. +- `medium`: Medium and small request bodies (up to 10,000 bytes) will be captured. - `always`: The SDK will always capture the request body as long as Sentry can make sense of it. Please note that the Sentry server [limits HTTP request body size](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/#variable-size). The server always enforces its size limit, regardless of how you configure this option. @@ -577,7 +577,7 @@ The threshold in milliseconds for adding the source location to an outgoing HTTP - + An optional property that disables tracing for HTTP requests with certain status codes. diff --git a/docs/platforms/python/data-management/data-collected.mdx b/docs/platforms/python/data-management/data-collected.mdx index 76f8e740d80726..08c5b4c716f899 100644 --- a/docs/platforms/python/data-management/data-collected.mdx +++ b/docs/platforms/python/data-management/data-collected.mdx @@ -12,7 +12,7 @@ The category types and amount of data collected vary, depending on the integrati You can control many of the categories listed here with the `data_collection` option, which lets you opt in or out of each data category individually. -The `send_default_pii` option is still fully supported. We plan to eventually deprecate it in favor of `data_collection`, but that won't happen until a future major version. +The `send_default_pii` option is still supported, but `send_default_pii` will be removed in version 3.0 of the SDK. How much data the SDK collects by default depends on which option you use. Without `data_collection` (and with `send_default_pii` unset or `False`), the SDK collects conservatively, and the defaults described on this page apply. @@ -28,8 +28,6 @@ Regardless of these options, you can always scrub any data before it's sent to S By default, the Sentry SDK sends HTTP request headers to Sentry but filters out any headers that contain sensitive data. (See the [list of headers](https://github.com/getsentry/sentry-python/blob/master/sentry_sdk/integrations/_wsgi_common.py#L28-L35) that are filtered). The Python SDK doesn't capture response headers. -To send all HTTP headers, set `send_default_pii=True` in the `sentry_sdk.init()` call. - When using `data_collection`, request headers are collected with sensitive values scrubbed. Use `http_headers` to control this: ```python @@ -50,14 +48,14 @@ sentry_sdk.init( Values whose keys match Sentry's built-in sensitive denylist (such as `auth`, `token`, or `password`) are always scrubbed, while the keys are kept. See [Key-Value Collection Behavior](#key-value-collection-behavior) below for details on `mode` and `terms`. +If you use `send_default_pii` instead, set it to `True` in the `sentry_sdk.init()` call to send all HTTP headers. + Additionally a [data scrubber](/platforms/python/data-management/sensitive-data/) removes sensitive data from headers (and a lot of other fields) right before sending data to Sentry. ## Cookies By default, the Sentry SDK doesn't send cookies. Sentry tries to remove any cookies that contain sensitive information, such as the Session ID and CSRF Token cookies in Django. -If you want to send cookies, set `send_default_pii=True` in the `sentry_sdk.init()` call. - When using `data_collection`, cookies are collected by default with sensitive values scrubbed. Opt out with `{"mode": "off"}`, or restrict which values are sent using `"allowlist"` or `"denylist"` mode: ```python @@ -71,14 +69,14 @@ sentry_sdk.init( ) ``` +If you use `send_default_pii` instead, set it to `True` in the `sentry_sdk.init()` call to send cookies. + Additionally a [data scrubber](/platforms/python/data-management/sensitive-data/) removes sensitive data from cookies (and a lot of other fields) right before sending data to Sentry. ## Information About Logged-in User By default, the Sentry SDK doesn't send any information about the logged-in user, such as email address, user ID, or username. Even if enabled, the type of logged-in user information you'll be able to send depends on the integrations you enable in Sentry's SDK. Most integrations won't send any user information. Some will only set the user ID, but there are a few that will set the user ID, username, and email address. -To start sending logged-in user information, set `send_default_pii=True` in the `sentry_sdk.init()` call. - When using `data_collection`, the SDK populates user identity fields (`user.id`, `user.email`, `user.username`) from instrumentation by default. To disable this, set `user_info` to `False`: ```python @@ -92,12 +90,12 @@ sentry_sdk.init( ) ``` +If you use `send_default_pii` instead, set it to `True` in the `sentry_sdk.init()` call to start sending logged-in user information. + ## Users' IP Address By default, the Sentry SDK doesn't send the user's IP address. Even if enabled, whether you're able to send the user's IP address or not, will depend on the integrations you enable in Sentry's SDK. Most integrations won't set the user's IP address at all. -To enable sending the user's IP address, set `send_default_pii=True` in the `sentry_sdk.init()` call. - When using `data_collection`, the user's IP address is sent by default. Disable it by setting `user_info` to `False`. Even when this is disabled, IP addresses can still reach Sentry through collected HTTP headers, cookies, or query parameters (for example, the `X-Forwarded-For` header). If you use `data_collection`, add these terms to the deny lists for those categories so their values are filtered: @@ -126,6 +124,8 @@ sentry_sdk.init( ) ``` +If you use `send_default_pii` instead, set it to `True` in the `sentry_sdk.init()` call to send the user's IP address. + ## Request URL The full request URL of outgoing and incoming HTTP requests is **always sent to Sentry**. Depending on your application, this could contain PII data. @@ -161,7 +161,7 @@ The request body of incoming HTTP requests can be sent to Sentry. Whether it's s If you want to prevent bodies from being sent to Sentry altogether, set `max_request_body_size` to `"never"`. -When using `data_collection`, incoming and outgoing request bodies are collected by default. To disable body collection, set `http_bodies` to an empty list, or provide only the body types you want: +When using `data_collection`, incoming and outgoing request bodies, as well as outgoing response bodies, are collected by default. To disable body collection, set `http_bodies` to an empty list, or provide only the body types you want: ```python import sentry_sdk @@ -175,7 +175,7 @@ sentry_sdk.init( ) ``` -The valid body types are `"incoming_request"` and `"outgoing_request"`. The Python SDK doesn't capture response bodies, so there are no response body types. +The valid body types are `"incoming_request"`, `"outgoing_request"`, and `"outgoing_response"`. Currently, only the Ariadne and Strawberry integrations use `"outgoing_response"`, to attach the GraphQL response to error events. The Python SDK doesn't capture incoming response bodies. `max_request_body_size` still applies on top of `http_bodies`. @@ -272,9 +272,7 @@ Without `data_collection` (and with `send_default_pii` unset or `False`), this d ## LLM Inputs And Responses -When using Sentry in your AI apps, the SDK by default won't add data like LLM inputs and responses to spans. To start recording these, add `send_default_pii=True` to your `sentry_sdk.init()` call. - -Most AI integrations have an additional parameter to control whether prompts should be included called `include_prompts`. See the documentation for the specific AI framework for more information. +When using Sentry in your AI apps, the SDK by default won't add LLM prompts, messages, or responses to spans. Some integrations still attach tool data by default, such as tool definitions and MCP tool arguments. See the documentation for the specific AI framework for details on what's attached and how to remove it. When using `data_collection`, the `gen_ai` category records both inputs and outputs unless you opt out. Metadata like the model ID and token counts is always collected. @@ -291,6 +289,8 @@ sentry_sdk.init( `gen_ai` supersedes the per-integration `include_prompts` parameter. When `data_collection` is set, `gen_ai` determines whether prompt content is recorded, regardless of what an individual integration's `include_prompts` is set to. +If you use `send_default_pii` instead, add `send_default_pii=True` to your `sentry_sdk.init()` call to start recording LLM inputs and responses. Most AI integrations have an additional parameter to control whether prompts should be included called `include_prompts`. See the documentation for the specific AI framework for more information. + ## `data_collection` Reference ### Keys @@ -300,7 +300,7 @@ sentry_sdk.init( | `user_info` | `bool` | `True` | Populate `user.*` fields (`id`, `email`, `username`, `ip_address`) from instrumentation. | | `cookies` | key-value behavior | `{"mode": "denylist"}` | Collect cookies. | | `http_headers` | `{"request": key-value behavior}` | `{"request": {"mode": "denylist"}}` | Collect HTTP request headers. The Python SDK currently doesn't capture response headers. | -| `http_bodies` | `list[str]` | `["incoming_request", "outgoing_request"]` | Body types to collect. Set to `[]` to disable. The Python SDK currently doesn't capture response bodies. | +| `http_bodies` | `list[str]` | `["incoming_request", "outgoing_request", "outgoing_response"]` | Body types to collect. Set to `[]` to disable. The Python SDK currently doesn't capture incoming response bodies. | | `url_query_params` | key-value behavior | `{"mode": "denylist"}` | Collect URL query parameters. | | `graphql` | `{"document": bool, "variables": bool}` | both `True` | Collect the GraphQL query document and its variables. | | `gen_ai` | `{"inputs": bool, "outputs": bool}` | both `True` | Collect generative AI input and output content. Metadata such as the model ID and token counts is always collected. | diff --git a/docs/platforms/python/data-management/sensitive-data/index.mdx b/docs/platforms/python/data-management/sensitive-data/index.mdx index e12b491821416b..ed92f8e4d661fa 100644 --- a/docs/platforms/python/data-management/sensitive-data/index.mdx +++ b/docs/platforms/python/data-management/sensitive-data/index.mdx @@ -33,7 +33,7 @@ Ensure that your team is aware of your company's policy around what can and cann The SDK can be configured to collect or ignore specific data using the [`data_collection`](../../configuration/options/#data_collection) option. -Alternately, you can use the simpler [`send_default_pii`](../../configuration/options/#send_default_pii) option by setting it to `True` or `False`. Note that this option will be phased out in favor of the more fine-grained [`data_collection`](../../configuration/options/#data_collection). +Alternately, you can use the simpler [`send_default_pii`](../../configuration/options/#send_default_pii) option by setting it to `True` or `False`. Note that `send_default_pii` will be removed in version 3.0 of the SDK in favor of the more fine-grained [`data_collection`](../../configuration/options/#data_collection). If you _do not_ wish to use the default PII behavior, you can also choose to identify users in a more controlled manner, using our [user identity context](../../enriching-events/identify-user/). diff --git a/docs/platforms/python/index.mdx b/docs/platforms/python/index.mdx index 727dd24fca87a8..245773b8724b11 100644 --- a/docs/platforms/python/index.mdx +++ b/docs/platforms/python/index.mdx @@ -51,9 +51,10 @@ from sentry_sdk import metrics sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add request headers and IP for users, - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% diff --git a/docs/platforms/python/integrations/aiomysql/index.mdx b/docs/platforms/python/integrations/aiomysql/index.mdx index aef1be7f028970..64345d846c7568 100644 --- a/docs/platforms/python/integrations/aiomysql/index.mdx +++ b/docs/platforms/python/integrations/aiomysql/index.mdx @@ -32,9 +32,10 @@ sentry_sdk.init( # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. traces_sample_rate=1.0, - # Add data like inputs and responses; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "database_query_data": True, + }, integrations=[ AioMySQLIntegration(), ], @@ -52,7 +53,10 @@ import asyncio sentry_sdk.init( dsn="___PUBLIC_DSN___", traces_sample_rate=1.0, - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "database_query_data": True, + }, integrations=[ AioMySQLIntegration(), ], diff --git a/docs/platforms/python/integrations/ariadne/index.mdx b/docs/platforms/python/integrations/ariadne/index.mdx index 25c8f37b42b7b1..7f082a1e4c9beb 100644 --- a/docs/platforms/python/integrations/ariadne/index.mdx +++ b/docs/platforms/python/integrations/ariadne/index.mdx @@ -78,12 +78,27 @@ This will create a corresponding `GraphQLError` in the Issues section of ## Options The Ariadne integration can capture request and response payload for each GraphQL -error that happens. Since these may contain sensitive data, the SDK needs to be -initialized with the -[send_default_pii](/platforms/python/configuration/options/#send-default-pii) -option set to `True`. +error that happens. Since these may contain sensitive data, no request and response +data will be attached by default. -By default, no request and response data will be attached. +To attach this data, use the `data_collection` option. The `graphql` key controls the query document and its variables in the request +payload, and the `outgoing_response` entry in `http_bodies` controls the response +payload: + +```python +sentry_sdk.init( + # same options as above + data_collection={ + "graphql": {"document": True, "variables": True}, + "http_bodies": ["incoming_request", "outgoing_request", "outgoing_response"], + }, +) +``` + +These are also the defaults when you pass a `data_collection` dictionary, so you only +need to set the keys you want to change. See Data Collected for all available keys. + +Alternatively, you can initialize the SDK with the `send_default_pii` option set to `True`, though `send_default_pii` will be removed in version 3.0 of the SDK: ```python sentry_sdk.init( @@ -96,7 +111,8 @@ sentry_sdk.init( Since `send_default_pii` is a global SDK option, setting it to `True` will affect all integrations, not just Ariadne. Please make sure to [scrub sensitive data](/platforms/python/data-management/sensitive-data/) -from events before enabling this option. +from events before enabling this option. With `data_collection`, you can enable +only the categories you need instead. diff --git a/docs/platforms/python/integrations/asgi/index.mdx b/docs/platforms/python/integrations/asgi/index.mdx index 22e2bebd6016b0..aa54565fbf41d7 100644 --- a/docs/platforms/python/integrations/asgi/index.mdx +++ b/docs/platforms/python/integrations/asgi/index.mdx @@ -41,9 +41,10 @@ from my_asgi_app import app sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. @@ -102,7 +103,7 @@ Additionally, a transaction will show up in the "Performance" section on [sentry ## Behavior -- Request data is attached to all events: **HTTP method, URL, headers**. Sentry excludes raw bodies and multipart file uploads. Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you set `send_default_pii` to `True`. +- Request data is attached to all events: **HTTP method, URL, headers**. Sentry excludes raw bodies and multipart file uploads. Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you configure which categories to collect with the `data_collection` option or set `send_default_pii` to `True`. `send_default_pii` will be removed in version 3.0 of the SDK. - Each request has a separate scope. Changes to the scope within a view, for example setting a tag, will only apply to events sent as part of the request being handled. diff --git a/docs/platforms/python/integrations/asyncio/index.mdx b/docs/platforms/python/integrations/asyncio/index.mdx index 4747d2a0369c1a..cb890f628fcd59 100644 --- a/docs/platforms/python/integrations/asyncio/index.mdx +++ b/docs/platforms/python/integrations/asyncio/index.mdx @@ -37,9 +37,10 @@ from sentry_sdk.integrations.asyncio import AsyncioIntegration async def main(): sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. @@ -75,9 +76,10 @@ from sentry_sdk.integrations.asyncio import enable_asyncio_integration # Initializing the SDK as early as possible, when there is no event loop yet sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. diff --git a/docs/platforms/python/integrations/aws-lambda/manual-instrumentation/index.mdx b/docs/platforms/python/integrations/aws-lambda/manual-instrumentation/index.mdx index 4675d89591cbbf..95942b5485dfc8 100644 --- a/docs/platforms/python/integrations/aws-lambda/manual-instrumentation/index.mdx +++ b/docs/platforms/python/integrations/aws-lambda/manual-instrumentation/index.mdx @@ -44,9 +44,10 @@ from sentry_sdk.integrations.aws_lambda import AwsLambdaIntegration sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. @@ -95,7 +96,7 @@ With the AWS Lambda integration enabled, the Python SDK will: You can add more data as described here. -- Request data including **HTTP method, URL, headers, form data, and JSON payloads** will be attached to all events. Sentry excludes raw bodies and multipart file uploads. Sentry also excludes personally identifiable information such as user ids, usernames, cookies, authorization headers, and IP addresses (unless you set `send_default_pii` to `True`). +- Request data including **HTTP method, URL, headers, form data, and JSON payloads** will be attached to all events. Sentry excludes raw bodies and multipart file uploads. Sentry also excludes personally identifiable information such as user ids, usernames, cookies, authorization headers, and IP addresses, unless you configure which categories to collect with the `data_collection` option or set `send_default_pii` to `True`. `send_default_pii` will be removed in version 3.0 of the SDK. - Each request has a separate scope. Changes to the scope within a view, for example setting a tag, will only apply to events sent as part of the request being handled. diff --git a/docs/platforms/python/integrations/beam/index.mdx b/docs/platforms/python/integrations/beam/index.mdx index 774a0733212b5a..b90644d9859c03 100644 --- a/docs/platforms/python/integrations/beam/index.mdx +++ b/docs/platforms/python/integrations/beam/index.mdx @@ -29,9 +29,10 @@ from sentry_sdk.integrations.beam import BeamIntegration sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. diff --git a/docs/platforms/python/integrations/bottle/index.mdx b/docs/platforms/python/integrations/bottle/index.mdx index 2ee76609557e06..78e85a4331b9c0 100644 --- a/docs/platforms/python/integrations/bottle/index.mdx +++ b/docs/platforms/python/integrations/bottle/index.mdx @@ -54,7 +54,7 @@ It takes a couple of moments for the data to appear in [sentry.io](https://sentr - All exceptions leading to an Internal Server Error are reported. -- Request data is attached to all events: **HTTP method, URL, headers, form data, JSON payloads**. Sentry excludes raw bodies and multipart file uploads. Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you set `send_default_pii` to `True`. +- Request data is attached to all events: **HTTP method, URL, headers, form data, JSON payloads**. Sentry excludes raw bodies and multipart file uploads. Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you configure which categories to collect with the `data_collection` option or set `send_default_pii` to `True`. `send_default_pii` will be removed in version 3.0 of the SDK. - Each request has a separate scope. Changes to the scope within a view, for example setting a tag, will only apply to events sent as part of the request being handled. diff --git a/docs/platforms/python/integrations/celery/crons.mdx b/docs/platforms/python/integrations/celery/crons.mdx index ee8ea911e7cef6..c269ac7e4c2067 100644 --- a/docs/platforms/python/integrations/celery/crons.mdx +++ b/docs/platforms/python/integrations/celery/crons.mdx @@ -64,9 +64,10 @@ from sentry_sdk.integrations.celery import CeleryIntegration def init_sentry(**kwargs): sentry_sdk.init( dsn='___PUBLIC_DSN___', - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "queues": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. diff --git a/docs/platforms/python/integrations/celery/index.mdx b/docs/platforms/python/integrations/celery/index.mdx index 54494ff8d209f1..e8aac809354979 100644 --- a/docs/platforms/python/integrations/celery/index.mdx +++ b/docs/platforms/python/integrations/celery/index.mdx @@ -67,9 +67,10 @@ app = Celery("tasks", broker="...") def init_sentry(**_kwargs): sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add request headers and IP for users, - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "queues": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. @@ -106,9 +107,10 @@ def main(): # Initializing Sentry SDK in our process sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "queues": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. diff --git a/docs/platforms/python/integrations/chalice/index.mdx b/docs/platforms/python/integrations/chalice/index.mdx index 8b54681be4d305..00367578f4898d 100644 --- a/docs/platforms/python/integrations/chalice/index.mdx +++ b/docs/platforms/python/integrations/chalice/index.mdx @@ -43,7 +43,7 @@ When you enter the `"/"` route or the scheduled task is run, an error event will ## Behavior -- Request data is attached to all events: HTTP method, URL, headers, form data, JSON payloads. Sentry excludes raw bodies and multipart file uploads. Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you set send_default_pii to True. +- Request data is attached to all events: HTTP method, URL, headers, form data, JSON payloads. Sentry excludes raw bodies and multipart file uploads. Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you configure which categories to collect with the `data_collection` option or set `send_default_pii` to `True`. `send_default_pii` will be removed in version 3.0 of the SDK. - Each request has a separate scope. Changes to the scope within a view, for example setting a tag, will only apply to events sent as part of the request being handled. diff --git a/docs/platforms/python/integrations/clickhouse-driver/index.mdx b/docs/platforms/python/integrations/clickhouse-driver/index.mdx index cecfb707cf04da..a4b518f2315c7f 100644 --- a/docs/platforms/python/integrations/clickhouse-driver/index.mdx +++ b/docs/platforms/python/integrations/clickhouse-driver/index.mdx @@ -27,7 +27,7 @@ If you have the `clickhouse-driver` package in your dependencies, the clickhouse -By default, the parameters of the query are not retrieved. To see the query parameters in Sentry, enable `send_default_pii`. See Basic Options for details. +By default, the parameters of the query are not retrieved. To see the query parameters in Sentry, enable `database_query_data` in the `data_collection` option, or enable `send_default_pii`. `send_default_pii` will be removed in version 3.0 of the SDK. ## Verify diff --git a/docs/platforms/python/integrations/cloudresourcecontext/index.mdx b/docs/platforms/python/integrations/cloudresourcecontext/index.mdx index 214eff25e971db..280b7a6bae09ec 100644 --- a/docs/platforms/python/integrations/cloudresourcecontext/index.mdx +++ b/docs/platforms/python/integrations/cloudresourcecontext/index.mdx @@ -42,9 +42,10 @@ from sentry_sdk.integrations.cloud_resource_context import CloudResourceContextI sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. diff --git a/docs/platforms/python/integrations/django/index.mdx b/docs/platforms/python/integrations/django/index.mdx index 574b1ad3771d3f..5eef058c811437 100644 --- a/docs/platforms/python/integrations/django/index.mdx +++ b/docs/platforms/python/integrations/django/index.mdx @@ -50,9 +50,10 @@ from sentry_sdk import metrics sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. @@ -76,7 +77,7 @@ To further customize your setup, review the [Options section](#options) below. Sentry automatically captures errors and reports issues for you. You can also expect the following for your Django project: -- If you use `django.contrib.auth`, and you've set `send_default_pii=True` in your call to `init`, user data (such as current user ID, email address, username) will be attached to error events. +- If you use `django.contrib.auth`, and you've either enabled `user_info` in the `data_collection` option or set `send_default_pii=True` in your call to `init`, user data (such as current user ID, email address, username) will be attached to error events. `send_default_pii` will be removed in version 3.0 of the SDK. - Request data will be attached to all events: **HTTP method, URL, headers, form data, JSON payloads**. Sentry excludes raw bodies and multipart file uploads. - Logs emitted by any logger will be recorded as breadcrumbs by the [Logging](/platforms/python/integrations/logging/) integration (this integration is enabled by default). diff --git a/docs/platforms/python/integrations/dramatiq/index.mdx b/docs/platforms/python/integrations/dramatiq/index.mdx index 6905d813cb7e0c..223474c1601737 100644 --- a/docs/platforms/python/integrations/dramatiq/index.mdx +++ b/docs/platforms/python/integrations/dramatiq/index.mdx @@ -35,9 +35,10 @@ from sentry_sdk.integrations.dramatiq import DramatiqIntegration sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, integrations=[ DramatiqIntegration(), ], diff --git a/docs/platforms/python/integrations/falcon/index.mdx b/docs/platforms/python/integrations/falcon/index.mdx index cf55207a13aeb1..ad966bb3badcc6 100644 --- a/docs/platforms/python/integrations/falcon/index.mdx +++ b/docs/platforms/python/integrations/falcon/index.mdx @@ -57,7 +57,7 @@ It takes a couple of moments for the data to appear in [sentry.io](https://sentr - All exceptions leading to an Internal Server Error are reported. -- Request data is attached to all events: **HTTP method, URL, headers, form data, JSON payloads**. Sentry excludes raw bodies and multipart file uploads. Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you set `send_default_pii` to `True`. +- Request data is attached to all events: **HTTP method, URL, headers, form data, JSON payloads**. Sentry excludes raw bodies and multipart file uploads. Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you configure which categories to collect with the `data_collection` option or set `send_default_pii` to `True`. `send_default_pii` will be removed in version 3.0 of the SDK. - Each request has a separate scope. Changes to the scope within a view, for example setting a tag, will only apply to events sent as part of the request being handled. diff --git a/docs/platforms/python/integrations/fastapi/index.mdx b/docs/platforms/python/integrations/fastapi/index.mdx index 7b7752cdcec823..1d930ba2d30216 100644 --- a/docs/platforms/python/integrations/fastapi/index.mdx +++ b/docs/platforms/python/integrations/fastapi/index.mdx @@ -59,7 +59,7 @@ You can also expect the following for your FastAPI project: - By default, all exceptions leading to an Internal Server Error are captured and reported. The HTTP status codes to report on are configurable via the `failed_request_status_codes` [option](#options). - Request data will be attached to all events: HTTP method, URL, headers, form data, JSON payloads. Sentry excludes raw bodies and multipart file uploads. -- Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you set `send_default_pii` to `True`. +- Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you configure which categories to collect with the `data_collection` option or set `send_default_pii` to `True`. `send_default_pii` will be removed in version 3.0 of the SDK. To learn how to manually report issues, see Capturing Errors. diff --git a/docs/platforms/python/integrations/flask/index.mdx b/docs/platforms/python/integrations/flask/index.mdx index 970c6ccd891a74..475392cd9660ad 100644 --- a/docs/platforms/python/integrations/flask/index.mdx +++ b/docs/platforms/python/integrations/flask/index.mdx @@ -59,7 +59,7 @@ To further customize your setup, review the [Options section](#options) below. Sentry automatically captures errors and reports issues for you. You can also expect the following for your Flask app: -- If you use `flask-login`, and you've set `send_default_pii=True` in your call to `init`, user data (such as current user ID, email address, username) will be attached to error events. +- If you use `flask-login`, and you've either enabled `user_info` in the `data_collection` option or set `send_default_pii=True` in your call to `init`, user data (such as current user ID, email address, username) will be attached to error events. `send_default_pii` will be removed in version 3.0 of the SDK. - Request data will be attached to all events: HTTP method, URL, headers, form data, JSON payloads. Sentry excludes raw bodies and multipart file uploads. - Logs emitted by any `app.logger` or _any_ logger will be recorded by the [Logging](/platforms/python/integrations/logging/) integration (this integration is enabled by default). diff --git a/docs/platforms/python/integrations/gcp-functions/index.mdx b/docs/platforms/python/integrations/gcp-functions/index.mdx index 9b35ef21b0ec17..a12ba3305f1c70 100644 --- a/docs/platforms/python/integrations/gcp-functions/index.mdx +++ b/docs/platforms/python/integrations/gcp-functions/index.mdx @@ -39,9 +39,10 @@ from sentry_sdk.integrations.gcp import GcpIntegration sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. @@ -105,6 +106,6 @@ With the Google Cloud Functions integration enabled, the Python SDK will: - Function configured time (in seconds) - You can add more data as described here -- Request data is attached to all events: **HTTP method, URL, headers, form data, JSON payloads**. Sentry excludes raw bodies and multipart file uploads. Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you set `send_default_pii` to `True`. +- Request data is attached to all events: **HTTP method, URL, headers, form data, JSON payloads**. Sentry excludes raw bodies and multipart file uploads. Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you configure which categories to collect with the `data_collection` option or set `send_default_pii` to `True`. `send_default_pii` will be removed in version 3.0 of the SDK. - Each request has a separate scope. Changes to the scope within a view, for example setting a tag, will only apply to events sent as part of the request being handled. diff --git a/docs/platforms/python/integrations/gnu_backtrace/index.mdx b/docs/platforms/python/integrations/gnu_backtrace/index.mdx index 3d2ef0206b3792..df49c32f5cc39c 100644 --- a/docs/platforms/python/integrations/gnu_backtrace/index.mdx +++ b/docs/platforms/python/integrations/gnu_backtrace/index.mdx @@ -29,9 +29,10 @@ from sentry_sdk.integrations.gnu_backtrace import GnuBacktraceIntegration sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, integrations=[ GnuBacktraceIntegration(), ], diff --git a/docs/platforms/python/integrations/gql/index.mdx b/docs/platforms/python/integrations/gql/index.mdx index 83dabd42c16e2a..fa6be7b4b4834d 100644 --- a/docs/platforms/python/integrations/gql/index.mdx +++ b/docs/platforms/python/integrations/gql/index.mdx @@ -28,17 +28,24 @@ If you have the `gql` package in your dependencies, the GQL integration will be ## Data Privacy and the GQL Integration -To ensure data privacy, the SDK avoids sending any information that may potentially contain personally identifiable information (PII) by default. See the docs for the [`send_default_pii` flag](/platforms/python/configuration/options/#send-default-pii) for more information. +To ensure data privacy, the SDK avoids sending any information that may potentially contain personally identifiable information (PII) by default. See the docs for the `data_collection` and `send_default_pii` options for more information. -For the GQL integration, this policy means that the SDK **doesn't send** the GraphQL queries and the `errors` information that the GraphQL server returns, unless you override the default configuration via the `send_default_pii` flag. +For the GQL integration, this policy means that the SDK **doesn't send** the GraphQL queries and the `errors` information that the GraphQL server returns, unless you override the default configuration. - +To have Sentry record the GraphQL queries and the `errors` information returned by the GraphQL server, enable the `graphql` key of the `data_collection` option in your SDK init. The `document` key controls the queries and the `errors` information, and the `variables` key controls the query variables: -Before enabling the `send_default_pii` flag, ensure you've configured Sentry's [sensitive data scrubbing](/platforms/python/data-management/sensitive-data/) tools to scrub all PII. +```python +sentry_sdk.init( + # ... + data_collection={ + "graphql": {"document": True, "variables": True}, + }, +) +``` - +These are also the defaults when you pass a `data_collection` dictionary. See Data Collected for all available keys. -To have Sentry record the GraphQL queries and the `errors` information returned by the GraphQL server, add the following to your SDK init: +Alternatively, you can set `send_default_pii` to `True`, though `send_default_pii` will be removed in version 3.0 of the SDK: ```python sentry_sdk.init( @@ -48,3 +55,9 @@ sentry_sdk.init( send_default_pii=True, ) ``` + + + +Before enabling the `send_default_pii` flag, ensure you've configured Sentry's [sensitive data scrubbing](/platforms/python/data-management/sensitive-data/) tools to scrub all PII. Since `send_default_pii` affects all integrations, consider using `data_collection` to enable only the categories you need instead. + + diff --git a/docs/platforms/python/integrations/graphene/index.mdx b/docs/platforms/python/integrations/graphene/index.mdx index 31a27b69e7acdd..02ba4011bd6c48 100644 --- a/docs/platforms/python/integrations/graphene/index.mdx +++ b/docs/platforms/python/integrations/graphene/index.mdx @@ -62,10 +62,24 @@ by default. To capture request bodies: -- Initialize the SDK with the - [send_default_pii](/platforms/python/configuration/options/#send-default-pii) - option set to `True`. - Make sure the integration for the web framework you're using is enabled. +- Initialize the SDK with the `data_collection` option. The `graphql` key's `document` setting controls whether the GraphQL + request body is attached. If you set `http_bodies`, it must include + `incoming_request` so that your web framework integration captures the body + in the first place. + +```python +sentry_sdk.init( + # same options as above + data_collection={ + "graphql": {"document": True}, + }, +) +``` + +Both are enabled by default when you pass a `data_collection` dictionary. See Data Collected for all available keys. + +Alternatively, you can initialize the SDK with the `send_default_pii` option set to `True`, though `send_default_pii` will be removed in version 3.0 of the SDK: ```python sentry_sdk.init( @@ -81,7 +95,8 @@ sentry_sdk.init( Since `send_default_pii` is a global SDK option, setting it to `True` affects all integrations, not just Graphene. Please make sure to take care of [scrubbing sensitive data](/platforms/python/data-management/sensitive-data/) -from events before enabling this option. +from events before enabling this option. With `data_collection`, you can enable +only the categories you need instead. diff --git a/docs/platforms/python/integrations/grpc/index.mdx b/docs/platforms/python/integrations/grpc/index.mdx index 621229b4209573..c731a310824da8 100644 --- a/docs/platforms/python/integrations/grpc/index.mdx +++ b/docs/platforms/python/integrations/grpc/index.mdx @@ -46,9 +46,10 @@ from sentry_sdk.integrations.grpc import GRPCIntegration sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. @@ -87,9 +88,10 @@ from sentry_sdk.integrations.grpc import GRPCIntegration sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. diff --git a/docs/platforms/python/integrations/launchdarkly/index.mdx b/docs/platforms/python/integrations/launchdarkly/index.mdx index c933d515edfdb1..dc08c9eb4effa7 100644 --- a/docs/platforms/python/integrations/launchdarkly/index.mdx +++ b/docs/platforms/python/integrations/launchdarkly/index.mdx @@ -26,9 +26,10 @@ from sentry_sdk.integrations.launchdarkly import LaunchDarklyIntegration sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, integrations=[ LaunchDarklyIntegration(), ], diff --git a/docs/platforms/python/integrations/litestar/index.mdx b/docs/platforms/python/integrations/litestar/index.mdx index f82832d2be64ac..672658b95c9005 100644 --- a/docs/platforms/python/integrations/litestar/index.mdx +++ b/docs/platforms/python/integrations/litestar/index.mdx @@ -36,9 +36,10 @@ import sentry_sdk sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. diff --git a/docs/platforms/python/integrations/logging/index.mdx b/docs/platforms/python/integrations/logging/index.mdx index 5cc0d10f6754c7..3cad947696cf0c 100644 --- a/docs/platforms/python/integrations/logging/index.mdx +++ b/docs/platforms/python/integrations/logging/index.mdx @@ -33,9 +33,10 @@ from sentry_sdk.integrations.logging import LoggingIntegration sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, integrations=[ LoggingIntegration(capture_sentry_logs=True), ], diff --git a/docs/platforms/python/integrations/loguru/index.mdx b/docs/platforms/python/integrations/loguru/index.mdx index 3931fc2b6c7a98..e9dcb80815aed9 100644 --- a/docs/platforms/python/integrations/loguru/index.mdx +++ b/docs/platforms/python/integrations/loguru/index.mdx @@ -36,9 +36,10 @@ from sentry_sdk.integrations.loguru import LoguruIntegration sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, integrations=[ LoguruIntegration(capture_sentry_logs=True), ], diff --git a/docs/platforms/python/integrations/mcp/index.mdx b/docs/platforms/python/integrations/mcp/index.mdx index 9c979a418cc822..f8c61f3a64fdde 100644 --- a/docs/platforms/python/integrations/mcp/index.mdx +++ b/docs/platforms/python/integrations/mcp/index.mdx @@ -47,9 +47,10 @@ from sentry_sdk.integrations.mcp import MCPIntegration sentry_sdk.init( dsn="___PUBLIC_DSN___", traces_sample_rate=1.0, - # Add data like tool inputs/outputs; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "gen_ai": {"inputs": True, "outputs": True}, + }, integrations=[ MCPIntegration(), ], @@ -74,9 +75,10 @@ from mcp.server.fastmcp import FastMCP sentry_sdk.init( dsn="___PUBLIC_DSN___", traces_sample_rate=1.0, - # Add data like tool inputs/outputs; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "gen_ai": {"inputs": True, "outputs": True}, + }, integrations=[ MCPIntegration(), ], @@ -131,7 +133,10 @@ from mcp.types import Tool, TextContent, GetPromptResult, PromptMessage sentry_sdk.init( dsn="___PUBLIC_DSN___", traces_sample_rate=1.0, - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "gen_ai": {"inputs": True, "outputs": True}, + }, integrations=[ MCPIntegration(), ], @@ -193,7 +198,21 @@ Data on the following will be collected: - **Request context**: Request IDs, session IDs, and transport types (stdio/HTTP) - **Execution spans**: Timing information for all handler invocations -Sentry considers tool inputs/outputs and prompt content as PII and doesn't include PII data by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude this data despite `send_default_pii=True`, configure the integration with `include_prompts=False` as shown in the [Options section](#options) below. +Sentry considers tool inputs/outputs and prompt content as PII. By default, it doesn't include tool results or prompt content, but tool and prompt arguments (`mcp.request.argument.*`) are still attached; setting `inputs` to `False` in the `gen_ai` key described below removes them. To include tool results and prompt content, use the `gen_ai` key of the `data_collection` option, which lets you control inputs and outputs separately. When you pass a `data_collection` dictionary, both are collected by default, and `include_prompts` is ignored: + +```python +sentry_sdk.init( + # ... + data_collection={ + # Collect tool and prompt inputs, but not outputs + "gen_ai": {"inputs": True, "outputs": False}, + }, +) +``` + +Setting `inputs` to `False` removes the `mcp.request.argument.*` attributes from spans, and setting `outputs` to `False` removes tool results and prompt message content. + +Alternatively, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude this data despite `send_default_pii=True`, configure the integration with `include_prompts=False` as shown in the [Options section](#options) below. `send_default_pii` will be removed in version 3.0 of the SDK. ### Captured Span Data @@ -208,7 +227,7 @@ For each operation, the following span data attributes are captured: **Tools:** - `mcp.tool.name`: The name of the tool being executed - `mcp.request.argument.*`: Tool input arguments -- `mcp.tool.result.content`: Tool output (when `send_default_pii=True`) +- `mcp.tool.result.content`: Tool output (when `gen_ai.outputs` is enabled in `data_collection`, or when `send_default_pii=True`) - `mcp.tool.result.is_error`: Whether the tool execution resulted in an error **Prompts:** @@ -216,7 +235,7 @@ For each operation, the following span data attributes are captured: - `mcp.request.argument.*`: Prompt input arguments - `mcp.prompt.result.message.count`: Number of messages in the prompt result - `mcp.prompt.result.message.role`: Role of the message (for single-message prompts) -- `mcp.prompt.result.message.content`: Message content (for single-message prompts, when `send_default_pii=True`) +- `mcp.prompt.result.message.content`: Message content (for single-message prompts, when `gen_ai.outputs` is enabled in `data_collection`, or when `send_default_pii=True`) **Resources:** - `mcp.resource.uri`: The URI of the resource being accessed @@ -247,7 +266,9 @@ You can pass the following keyword arguments to `MCPIntegration()`: - `include_prompts`: - Whether tool inputs/outputs and prompt content should be sent to Sentry. Sentry considers this data personal identifiable data (PII) by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False`. + Whether tool inputs/outputs and prompt content should be sent to Sentry. If you use the `data_collection` option, this option is ignored. Use the `gen_ai` key instead. + + Sentry considers this data personal identifiable data (PII) by default. If you want to include the data, set `send_default_pii=True` in the `sentry_sdk.init()` call. To explicitly exclude prompts and outputs despite `send_default_pii=True`, configure the integration with `include_prompts=False`. `send_default_pii` will be removed in version 3.0 of the SDK. The default is `True`. diff --git a/docs/platforms/python/integrations/openfeature/index.mdx b/docs/platforms/python/integrations/openfeature/index.mdx index c63118d04d7f61..676da33b506eb7 100644 --- a/docs/platforms/python/integrations/openfeature/index.mdx +++ b/docs/platforms/python/integrations/openfeature/index.mdx @@ -28,9 +28,10 @@ from sentry_sdk.integrations.openfeature import OpenFeatureIntegration sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, integrations=[ OpenFeatureIntegration(), ], diff --git a/docs/platforms/python/integrations/otlp/index.mdx b/docs/platforms/python/integrations/otlp/index.mdx index 00799eef4609bf..ac8a5b58eb877a 100644 --- a/docs/platforms/python/integrations/otlp/index.mdx +++ b/docs/platforms/python/integrations/otlp/index.mdx @@ -39,9 +39,10 @@ from sentry_sdk.integrations.otlp import OTLPIntegration sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, integrations=[ OTLPIntegration(), ], diff --git a/docs/platforms/python/integrations/pure_eval/index.mdx b/docs/platforms/python/integrations/pure_eval/index.mdx index 88b428af32fce4..b71bb19fb62fff 100644 --- a/docs/platforms/python/integrations/pure_eval/index.mdx +++ b/docs/platforms/python/integrations/pure_eval/index.mdx @@ -27,9 +27,10 @@ from sentry_sdk.integrations.pure_eval import PureEvalIntegration sentry_sdk.init( dns="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, integrations=[ PureEvalIntegration(), ], diff --git a/docs/platforms/python/integrations/pymongo/index.mdx b/docs/platforms/python/integrations/pymongo/index.mdx index 6eb54dff069c45..aea9b73f03d7e4 100644 --- a/docs/platforms/python/integrations/pymongo/index.mdx +++ b/docs/platforms/python/integrations/pymongo/index.mdx @@ -58,7 +58,7 @@ The following information about your MongoDB queries will be available to you on - Performance traces for all MongoDB queries - Breadcrumbs for all MongoDB queries -- Personal identifiable information (PII) will be stripped from all MongoDB queries if `send_default_pii` is disabled in the SDK. (This was tested for PyMongo 4.2 and below, but "should" also be future proof) +- Personal identifiable information (PII) will be stripped from all MongoDB queries unless you enable `database_query_data` in the `data_collection` option or set `send_default_pii` to `True`. (This was tested for PyMongo 4.2 and below, but "should" also be future proof) `send_default_pii` will be removed in version 3.0 of the SDK. ### Other MongoDB libraries diff --git a/docs/platforms/python/integrations/pyramid/index.mdx b/docs/platforms/python/integrations/pyramid/index.mdx index 5f6b80953790b5..033d0619abf85f 100644 --- a/docs/platforms/python/integrations/pyramid/index.mdx +++ b/docs/platforms/python/integrations/pyramid/index.mdx @@ -60,7 +60,7 @@ When you point your browser to [http://localhost:6543/](http://localhost:6543/) - exceptions that are not handled by any exception view - exceptions whose exception view returns a status code of 500 -- Request data is attached to all events: **HTTP method, URL, headers, form data, JSON payloads**. Sentry excludes raw bodies and multipart file uploads. Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you set `send_default_pii` to `True`. +- Request data is attached to all events: **HTTP method, URL, headers, form data, JSON payloads**. Sentry excludes raw bodies and multipart file uploads. Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you configure which categories to collect with the `data_collection` option or set `send_default_pii` to `True`. `send_default_pii` will be removed in version 3.0 of the SDK. - Each request has a separate scope. Changes to the scope within a view, for example setting a tag, will only apply to events sent as part of the request being handled. diff --git a/docs/platforms/python/integrations/pyreqwest/index.mdx b/docs/platforms/python/integrations/pyreqwest/index.mdx index cf5f633222a093..b4b53e3dd9a8e6 100644 --- a/docs/platforms/python/integrations/pyreqwest/index.mdx +++ b/docs/platforms/python/integrations/pyreqwest/index.mdx @@ -31,9 +31,10 @@ from sentry_sdk.integrations.pyreqwest import PyreqwestIntegration sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, integrations=[ PyreqwestIntegration(), ], diff --git a/docs/platforms/python/integrations/quart/index.mdx b/docs/platforms/python/integrations/quart/index.mdx index 7945c3a2773d69..0aaa51f3915c9e 100644 --- a/docs/platforms/python/integrations/quart/index.mdx +++ b/docs/platforms/python/integrations/quart/index.mdx @@ -52,7 +52,7 @@ It takes a couple of moments for the data to appear in [sentry.io](https://sentr - All exceptions leading to an Internal Server Error, from before/after serving functions, and background tasks are reported. -- Request data is attached to all events: **HTTP method, URL, headers**. Sentry also excludes personally identifiable information (such as user IDs, usernames, cookies, authorization headers, IP addresses) unless you set `send_default_pii` to `True`. +- Request data is attached to all events: **HTTP method, URL, headers**. Sentry also excludes personally identifiable information (such as user IDs, usernames, cookies, authorization headers, IP addresses) unless you configure which categories to collect with the `data_collection` option or set `send_default_pii` to `True`. `send_default_pii` will be removed in version 3.0 of the SDK. - Each request has a separate scope. Changes to the scope within a view, for example setting a tag, will only apply to events sent as part of the request being handled. diff --git a/docs/platforms/python/integrations/ray/index.mdx b/docs/platforms/python/integrations/ray/index.mdx index ef0561d2212baf..d309028888b67f 100644 --- a/docs/platforms/python/integrations/ray/index.mdx +++ b/docs/platforms/python/integrations/ray/index.mdx @@ -40,9 +40,10 @@ from sentry_sdk.integrations.ray import RayIntegration def init_sentry(): sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. diff --git a/docs/platforms/python/integrations/redis/index.mdx b/docs/platforms/python/integrations/redis/index.mdx index 85548a61992791..370de83b72bb33 100644 --- a/docs/platforms/python/integrations/redis/index.mdx +++ b/docs/platforms/python/integrations/redis/index.mdx @@ -27,7 +27,7 @@ The following information will be available to you on Sentry: - Performance information about requests to Redis will be available in the waterfall diagram in the [Traces](https://sentry.io/orgredirect/organizations/:orgslug/explore/traces/) section on Sentry. - Redis commands will be added as [breadcrumbs](/product/issues/issue-details/breadcrumbs/). -- If `send_default_pii` is set to `True` in your app's `sentry_sdk.init()` call, you will also see the data used in your Redis commands. +- If you enable `database_query_data` in the `data_collection` option, or set `send_default_pii` to `True` in your app's `sentry_sdk.init()` call, you will also see the data used in your Redis commands. `send_default_pii` will be removed in version 3.0 of the SDK. - Sentry will never collect data of the `AUTH` command. ## Verify Your Setup diff --git a/docs/platforms/python/integrations/rq/index.mdx b/docs/platforms/python/integrations/rq/index.mdx index 67447669455c2d..5196e5c164d028 100644 --- a/docs/platforms/python/integrations/rq/index.mdx +++ b/docs/platforms/python/integrations/rq/index.mdx @@ -39,9 +39,10 @@ import sentry_sdk sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "queues": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. @@ -77,9 +78,10 @@ import sentry_sdk sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "queues": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. @@ -126,9 +128,10 @@ import sentry_sdk # Sentry configuration for RQ worker processes sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "queues": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. @@ -159,9 +162,10 @@ import sentry_sdk # Sentry configuration for main.py process sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "queues": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. diff --git a/docs/platforms/python/integrations/rust_tracing/index.mdx b/docs/platforms/python/integrations/rust_tracing/index.mdx index 6bbbadc783af48..54a82156718855 100644 --- a/docs/platforms/python/integrations/rust_tracing/index.mdx +++ b/docs/platforms/python/integrations/rust_tracing/index.mdx @@ -187,7 +187,9 @@ The `pyo3-python-tracing-subscriber` crate has [a working example of a Sentry in A boolean controlling whether the values of a `tracing` span's key-value fields will be attached to the corresponding Sentry span. - If it is `None`, this behavior will be controlled by the `send_default_pii` option set during SDK initialization. If it is `False`, field values will be redacted on Sentry spans. If it is `True`, field values will be included on Sentry spans. + The `data_collection` option doesn't affect this behavior. If you use `data_collection` and want field values on your spans, set `include_tracing_fields` to `True` explicitly. + + If it is `None`, this behavior will be controlled by the `send_default_pii` option set during SDK initialization. If it is `False`, field values will be redacted on Sentry spans. If it is `True`, field values will be included on Sentry spans. `send_default_pii` will be removed in version 3.0 of the SDK. The default value of this option is `None`. diff --git a/docs/platforms/python/integrations/sanic/index.mdx b/docs/platforms/python/integrations/sanic/index.mdx index 544edd9cf7c142..edf2ff60971d60 100644 --- a/docs/platforms/python/integrations/sanic/index.mdx +++ b/docs/platforms/python/integrations/sanic/index.mdx @@ -46,9 +46,10 @@ app = Sanic(__main__) async def init_sentry(_): sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. @@ -123,7 +124,7 @@ When you point your browser to [http://localhost:8000/](http://localhost:8000/) - All exceptions leading to an Internal Server Error are reported. -- Request data is attached to all events: **HTTP method, URL, headers, form data, JSON payloads**. Sentry excludes raw bodies and multipart file uploads. Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you set `send_default_pii` to `True`. +- Request data is attached to all events: **HTTP method, URL, headers, form data, JSON payloads**. Sentry excludes raw bodies and multipart file uploads. Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you configure which categories to collect with the `data_collection` option or set `send_default_pii` to `True`. `send_default_pii` will be removed in version 3.0 of the SDK. - Each request has a separate scope. Changes to the scope within a view, for example setting a tag, will only apply to events sent as part of the request being handled. diff --git a/docs/platforms/python/integrations/serverless/index.mdx b/docs/platforms/python/integrations/serverless/index.mdx index 08dd0a45cc6b6a..df39e5ec668c33 100644 --- a/docs/platforms/python/integrations/serverless/index.mdx +++ b/docs/platforms/python/integrations/serverless/index.mdx @@ -46,9 +46,10 @@ from sentry_sdk.integrations.serverless import serverless_function sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. @@ -89,7 +90,7 @@ Now deploy your function. When you now run your function an error event will be - You can add more context as described here. -- Request data is attached to all events: **HTTP method, URL, headers, form data, JSON payloads**. Sentry excludes raw bodies and multipart file uploads. Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you set `send_default_pii` to `True`. +- Request data is attached to all events: **HTTP method, URL, headers, form data, JSON payloads**. Sentry excludes raw bodies and multipart file uploads. Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you configure which categories to collect with the `data_collection` option or set `send_default_pii` to `True`. `send_default_pii` will be removed in version 3.0 of the SDK. - Each request has a separate scope. Changes to the scope within a view, for example setting a tag, will only apply to events sent as part of the request being handled. diff --git a/docs/platforms/python/integrations/socket/index.mdx b/docs/platforms/python/integrations/socket/index.mdx index 4eb7e0c4bd6b2c..c1b49a1f78ecb5 100644 --- a/docs/platforms/python/integrations/socket/index.mdx +++ b/docs/platforms/python/integrations/socket/index.mdx @@ -37,9 +37,10 @@ from sentry_sdk.integrations.socket import SocketIntegration sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. diff --git a/docs/platforms/python/integrations/spark/index.mdx b/docs/platforms/python/integrations/spark/index.mdx index 2d2c57a03e7d54..24788abb982a9f 100644 --- a/docs/platforms/python/integrations/spark/index.mdx +++ b/docs/platforms/python/integrations/spark/index.mdx @@ -33,9 +33,10 @@ from sentry_sdk.integrations.spark import SparkIntegration if __name__ == "__main__": sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. @@ -76,9 +77,10 @@ import pyspark.daemon as original_daemon if __name__ == '__main__': sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. diff --git a/docs/platforms/python/integrations/starlette/index.mdx b/docs/platforms/python/integrations/starlette/index.mdx index f48f8c2937c439..7c76cf26af4c4a 100644 --- a/docs/platforms/python/integrations/starlette/index.mdx +++ b/docs/platforms/python/integrations/starlette/index.mdx @@ -58,7 +58,7 @@ You can also expect the following for your Starlette project: - By default, all exceptions leading to an Internal Server Error are reported. The HTTP status codes to report on are configurable via the `failed_request_status_codes` [option](#options). - Request data will be attached to all events: HTTP method, URL, headers, form data, JSON payloads. Sentry excludes raw bodies and multipart file uploads. -- Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you set `send_default_pii` to `True`. +- Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you configure which categories to collect with the `data_collection` option or set `send_default_pii` to `True`. `send_default_pii` will be removed in version 3.0 of the SDK. To learn how to manually report issues, see Capturing Errors. diff --git a/docs/platforms/python/integrations/statsig/index.mdx b/docs/platforms/python/integrations/statsig/index.mdx index 17be95497a5b5b..a530fbd9f6e316 100644 --- a/docs/platforms/python/integrations/statsig/index.mdx +++ b/docs/platforms/python/integrations/statsig/index.mdx @@ -26,9 +26,10 @@ from sentry_sdk.integrations.statsig import StatsigIntegration sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, integrations=[StatsigIntegration()], ) ``` diff --git a/docs/platforms/python/integrations/strawberry/index.mdx b/docs/platforms/python/integrations/strawberry/index.mdx index c808028f585afa..06db2ff9275095 100644 --- a/docs/platforms/python/integrations/strawberry/index.mdx +++ b/docs/platforms/python/integrations/strawberry/index.mdx @@ -39,9 +39,10 @@ from sentry_sdk.integrations.strawberry import StrawberryIntegration sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "graphql": {"document": True, "variables": True}, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. @@ -139,9 +140,25 @@ sentry_sdk.init( The Strawberry integration can capture request and response bodies for each GraphQL error that happens. Since these may contain sensitive data, -this is the default behavior. To enable capturing request and response bodies, the -SDK needs to be initialized with the -[send_default_pii](/platforms/python/configuration/options/#send-default-pii) option set to `True`. +this isn't the default behavior. + +To enable capturing request and response bodies, use the `data_collection` option. The `graphql` key controls the query document and its variables in the request +body, and the `outgoing_response` entry in `http_bodies` controls the response body: + +```python +sentry_sdk.init( + # ... + data_collection={ + "graphql": {"document": True, "variables": True}, + "http_bodies": ["incoming_request", "outgoing_request", "outgoing_response"], + }, +) +``` + +These are also the defaults when you pass a `data_collection` dictionary, so you only +need to set the keys you want to change. See Data Collected for all available keys. + +Alternatively, you can initialize the SDK with the `send_default_pii` option set to `True`, though `send_default_pii` will be removed in version 3.0 of the SDK: ```python sentry_sdk.init( @@ -155,7 +172,8 @@ sentry_sdk.init( Since `send_default_pii` is a global SDK option, setting it to `True` will affect all integrations, not just Strawberry. Please make sure to [remove sensitive data](/platforms/python/data-management/sensitive-data/) -from events before enabling this option. +from events before enabling this option. With `data_collection`, you can enable +only the categories you need instead. diff --git a/docs/platforms/python/integrations/sys_exit/index.mdx b/docs/platforms/python/integrations/sys_exit/index.mdx index ce84ee6c9cbb72..55aff23f907f6f 100644 --- a/docs/platforms/python/integrations/sys_exit/index.mdx +++ b/docs/platforms/python/integrations/sys_exit/index.mdx @@ -30,9 +30,10 @@ from sentry_sdk.integrations.sys_exit import SysExitIntegration sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, integrations=[SysExitIntegration()], ) ``` diff --git a/docs/platforms/python/integrations/tornado/index.mdx b/docs/platforms/python/integrations/tornado/index.mdx index 1ee3aabbd161e8..452849a127145a 100644 --- a/docs/platforms/python/integrations/tornado/index.mdx +++ b/docs/platforms/python/integrations/tornado/index.mdx @@ -61,7 +61,7 @@ It takes a couple of moments for the data to appear in [sentry.io](https://sentr - All exceptions leading to a Internal Server Error are reported. -- Request data is attached to all events: **HTTP method, URL, headers, form data, JSON payloads**. Sentry excludes raw bodies and multipart file uploads. Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you set `send_default_pii` to `True`. +- Request data is attached to all events: **HTTP method, URL, headers, form data, JSON payloads**. Sentry excludes raw bodies and multipart file uploads. Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you configure which categories to collect with the `data_collection` option or set `send_default_pii` to `True`. `send_default_pii` will be removed in version 3.0 of the SDK. - Each request has a separate scope. Changes to the scope within a view, for example setting a tag, will only apply to events sent as part of the request being handled. diff --git a/docs/platforms/python/integrations/tryton/index.mdx b/docs/platforms/python/integrations/tryton/index.mdx index 0c198d334133a3..49ec2d21caa327 100644 --- a/docs/platforms/python/integrations/tryton/index.mdx +++ b/docs/platforms/python/integrations/tryton/index.mdx @@ -29,9 +29,10 @@ from sentry_sdk.integrations.trytond import TrytondWSGIIntegration sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. @@ -80,7 +81,7 @@ def _(app, request, e): - All uncaught exceptions not inherited from Tryton exceptions are reported. -- Request data is attached to all events: **HTTP method, URL, headers, form data, JSON payloads**. Sentry excludes raw bodies and multipart file uploads. Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you set `send_default_pii` to `True`. +- Request data is attached to all events: **HTTP method, URL, headers, form data, JSON payloads**. Sentry excludes raw bodies and multipart file uploads. Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you configure which categories to collect with the `data_collection` option or set `send_default_pii` to `True`. `send_default_pii` will be removed in version 3.0 of the SDK. Each request has a separate scope. Changes to the scope within a view, for example setting a tag, will only apply to events sent as part of the request being handled. diff --git a/docs/platforms/python/integrations/typer/index.mdx b/docs/platforms/python/integrations/typer/index.mdx index 8be07fcae764dd..b7b9e9626db7db 100644 --- a/docs/platforms/python/integrations/typer/index.mdx +++ b/docs/platforms/python/integrations/typer/index.mdx @@ -26,9 +26,10 @@ from sentry_sdk.integrations.typer import TyperIntegration sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, integrations=[TyperIntegration()], ) ``` diff --git a/docs/platforms/python/integrations/unleash/index.mdx b/docs/platforms/python/integrations/unleash/index.mdx index 514f50fe010b0f..f0b2b0ce02a769 100644 --- a/docs/platforms/python/integrations/unleash/index.mdx +++ b/docs/platforms/python/integrations/unleash/index.mdx @@ -26,9 +26,10 @@ from sentry_sdk.integrations.unleash import UnleashIntegration sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, integrations=[UnleashIntegration()], ) ``` diff --git a/docs/platforms/python/integrations/wsgi/index.mdx b/docs/platforms/python/integrations/wsgi/index.mdx index b63b9f59ab8427..dd963ea1de8d44 100644 --- a/docs/platforms/python/integrations/wsgi/index.mdx +++ b/docs/platforms/python/integrations/wsgi/index.mdx @@ -41,9 +41,10 @@ from my_wsgi_app import app sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. @@ -89,7 +90,7 @@ make_server('', 8000, app).serve_forever() -- Request data is attached to all events: **HTTP method, URL, headers**. Sentry excludes raw bodies and multipart file uploads. Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you set `send_default_pii` to `True`. +- Request data is attached to all events: **HTTP method, URL, headers**. Sentry excludes raw bodies and multipart file uploads. Sentry also excludes personally identifiable information (such as user ids, usernames, cookies, authorization headers, IP addresses) unless you configure which categories to collect with the `data_collection` option or set `send_default_pii` to `True`. `send_default_pii` will be removed in version 3.0 of the SDK. Each request has a separate scope. Changes to the scope within a view, for example setting a tag, will only apply to events sent as part of the request being handled. diff --git a/docs/platforms/python/profiling/index.mdx b/docs/platforms/python/profiling/index.mdx index a5a015a20c07b8..2befc779e36aec 100644 --- a/docs/platforms/python/profiling/index.mdx +++ b/docs/platforms/python/profiling/index.mdx @@ -31,9 +31,10 @@ import sentry_sdk sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. traces_sample_rate=1.0, @@ -53,9 +54,10 @@ import sentry_sdk sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. traces_sample_rate=1.0, @@ -107,9 +109,10 @@ def profiles_sampler(sampling_context: SamplingContext) -> float: sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. traces_sample_rate=1.0, diff --git a/docs/platforms/python/tracing/index.mdx b/docs/platforms/python/tracing/index.mdx index c3db81d113485b..c83dd787f67c6e 100644 --- a/docs/platforms/python/tracing/index.mdx +++ b/docs/platforms/python/tracing/index.mdx @@ -22,9 +22,10 @@ import sentry_sdk sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. + traces_sample_rate=1.0, diff --git a/docs/platforms/python/tracing/instrumentation/custom-instrumentation/mcp-module.mdx b/docs/platforms/python/tracing/instrumentation/custom-instrumentation/mcp-module.mdx index 13cffde550d008..11d4e019a86551 100644 --- a/docs/platforms/python/tracing/instrumentation/custom-instrumentation/mcp-module.mdx +++ b/docs/platforms/python/tracing/instrumentation/custom-instrumentation/mcp-module.mdx @@ -59,7 +59,7 @@ with sentry_sdk.start_span( span.set_data("mcp.transport", "stdio") # or "http", "sse" for HTTP/WebSocket/SSE span.set_data("network.transport", "pipe") # or "tcp" for HTTP/SSE - # Set tool arguments (optional, if send_default_pii=True) + # Set tool arguments (keep in mind this might contain PII data, so only set if that's ok) for key, value in tool_arguments.items(): span.set_data(f"mcp.request.argument.{key}", value) @@ -105,7 +105,7 @@ with sentry_sdk.traces.start_span( "network.transport": "pipe", # or "tcp" for HTTP/SSE }) - # Set tool arguments (optional, if send_default_pii=True) + # Set tool arguments (keep in mind this might contain PII data, so only set if that's ok) for key, value in tool_arguments.items(): span.set_attribute(f"mcp.request.argument.{key}", value) diff --git a/docs/platforms/python/troubleshooting.mdx b/docs/platforms/python/troubleshooting.mdx index 5a05ac0423b736..af9a4f7cee0407 100644 --- a/docs/platforms/python/troubleshooting.mdx +++ b/docs/platforms/python/troubleshooting.mdx @@ -250,11 +250,7 @@ The continuous profiling feature was experimental prior to version `2.24.1`. To - - - Currently, we only support crontab expressions with five fields. - - + diff --git a/docs/platforms/react-native/common/configuration/webview.mdx b/docs/platforms/react-native/common/configuration/webview.mdx index 6dee56715513b1..8a874f02ba0de4 100644 --- a/docs/platforms/react-native/common/configuration/webview.mdx +++ b/docs/platforms/react-native/common/configuration/webview.mdx @@ -1,22 +1,91 @@ --- title: WebView -description: "Learn how to set up the Sentry React Native and Browser SDKs with React Native WebView." +description: "Learn how to connect traces and monitor errors and performance across the Sentry React Native and Browser SDKs with React Native WebView." --- -To monitor errors and performance in web views of React Native applications, you need to set up Sentry SDKs in both the mobile application and the web projects running in the web views. +To monitor errors and performance in web views of React Native applications, you set up Sentry SDKs in both the mobile application and the web projects running in the web views. You can also connect their traces, so a single distributed trace spans your React Native app and the web content it embeds. ## Application Monitoring -The Sentry React Native SDK doesn't interact with the mobile application's web views. To monitor errors and performance in the React Native part of the application follow the [Sentry React Native SDK setup instructions](/platforms/react-native/). +To monitor errors and performance in the React Native part of the application, follow the [Sentry React Native SDK setup instructions](/platforms/react-native/). The React Native SDK doesn't capture errors that happen inside a web view — those are captured by the JavaScript SDK running in the web project (see [WebView Monitoring](#webview-monitoring)). ## WebView Monitoring -To monitor errors and performance in web views choose the appropriate Sentry JavaScript SDK depending on the framework used in the web project. +To monitor errors and performance in web views, choose the appropriate Sentry JavaScript SDK depending on the framework used in the web project. - [Sentry React Native SDK](/platforms/react-native/) (if the web project uses React Native Web or Expo) - [Sentry React SDK](/platforms/javascript/guides/react/) (if the web project uses React) - [Other Sentry JavaScript SDKs](/platforms/javascript/) +## Connect Traces + + + +`sentryWebViewProps` is available from React Native SDK version `8.32.0`. + + + +Use `sentryWebViewProps` to inject the React Native app's trace into a web view. The Browser SDK running in the web page picks it up on pageload and continues the same trace, so the web page's pageload transaction and errors share the trace of your React Native app. The result is a single connected trace across the native and web parts of the user journey. + +Spread the props it returns onto your [`react-native-webview`](https://github.com/react-native-webview/react-native-webview) ``: + +```jsx +import { sentryWebViewProps } from "@sentry/react-native"; +import { WebView } from "react-native-webview"; + +; +``` + +For the connection to take effect: + +- The web page must run a Sentry [Browser SDK](/platforms/javascript/) with tracing enabled (the `browserTracingIntegration`). It continues the trace from the injected `sentry-trace` and `baggage` `` tags automatically — no additional configuration is needed on the web page. +- `allowedHosts` declares the hosts you trust to load in this WebView. A page is matched when its hostname equals an entry or is a subdomain of it (for example, `"example.com"` matches both `example.com` and `app.example.com`). Matching is case-insensitive, and the trace context is only written on matching pages. + + + +On iOS the trace tags are written before any page script runs. On **Android**, `react-native-webview` injects them asynchronously as the page starts, so they can land slightly after the page's first synchronous `` scripts. Load and initialize `@sentry/browser` the usual way — from a ` + + +``` + +```html {tabTitle:CDN} + + + +``` + +### Add Readable Stack Traces With Source Maps + + + +### Control the Data You Send to Sentry +## Send Logs + + + +If you're already logging with `console` or [Consola](https://github.com/unjs/consola), you can capture those logs with our console integrations. + + +## Send Application Metrics + + + ## Verify Your Setup - +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. + +Add a test button to one of your pages. Open the page in a browser and click the button to trigger an error for Sentry to capture. + +```html + + + +``` + + ### View Captured Data in Sentry -Now, head over to your project on [Sentry.io](https://sentry.io) to view the collected data (it takes a couple of moments for the data to appear). +Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). ## Next Steps -At this point, you should have integrated Sentry into your JavaScript application and should already be sending data to your Sentry project. - -Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are: +At this point, you should have integrated Sentry into your JavaScript application. Here's what to explore next: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup - Extend Sentry to your backend using one of our [SDKs](/) -- Learn how to [manually capture errors](/platforms/javascript/usage/) -- Continue to [customize your configuration](/platforms/javascript/configuration/) -- Get familiar with [Sentry's product features](/product/) like tracing, insights, and alerts +- Set up tunneling to avoid ad blockers from blocking Sentry events -- Find various support topics in troubleshooting +- Find various topics in Troubleshooting - [Get support](https://www.sentry.help/en/) diff --git a/platform-includes/getting-started-config/godot.mdx b/platform-includes/getting-started-config/godot.mdx index 12be12ec4e5c7f..2f86ca6954c76c 100644 --- a/platform-includes/getting-started-config/godot.mdx +++ b/platform-includes/getting-started-config/godot.mdx @@ -1,7 +1,7 @@ The minimum configuration required is the [DSN](/concepts/key-terms/dsn-explainer/) to your project. -Sentry can be configured via Project Settings or [in GDScript](/platforms/godot/configuration/options/). To access project settings in Godot Engine, navigate to `Project` > `Project Settings...`, then scroll down the sections list on the left until you find the Sentry section. +To access the project settings in Godot Engine, navigate to **Project > Project Settings...**, then scroll down the sections list on the left until you find the **Sentry** section. Enter your DSN in **Sentry > Options > DSN**. ![Sentry window](./img/godot_project_settings.png) -Your configuration is saved in the `project.godot` file along with other project settings. +Your configuration is saved in the `project.godot` file along with other project settings. With **Auto Init** turned on (the default), the SDK initializes automatically when your game starts, before any scenes load or scripts run. diff --git a/platform-includes/getting-started-config/javascript.node.mdx b/platform-includes/getting-started-config/javascript.node.mdx index 334bd8776680e8..f3797829ad2b4a 100644 --- a/platform-includes/getting-started-config/javascript.node.mdx +++ b/platform-includes/getting-started-config/javascript.node.mdx @@ -1,69 +1,43 @@ ```javascript {tabTitle:CommonJS} {filename: instrument.js} const Sentry = require("@sentry/node"); -// ___PRODUCT_OPTION_START___ profiling const { nodeProfilingIntegration } = require("@sentry/profiling-node"); -// ___PRODUCT_OPTION_END___ profiling - Sentry.init({ dsn: "___PUBLIC_DSN___", - // ___PRODUCT_OPTION_START___ profiling integrations: [ // Add our Profiling integration nodeProfilingIntegration(), ], - // ___PRODUCT_OPTION_END___ profiling - // ___PRODUCT_OPTION_START___ performance - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for tracing. - // We recommend adjusting this value in production - // Learn more at - // https://docs.sentry.io/platforms/javascript/guides/node/configuration/options/#tracesSampleRate + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ profiling - // Enable profiling for a percentage of sessions - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#profileSessionSampleRate + // Enables Profiling for every session. profileSessionSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ profiling }); ``` ```javascript {tabTitle:ESM} {filename: instrument.mjs} import * as Sentry from "@sentry/node"; -// ___PRODUCT_OPTION_START___ profiling import { nodeProfilingIntegration } from "@sentry/profiling-node"; -// ___PRODUCT_OPTION_END___ profiling // Ensure to call this before importing any other modules! Sentry.init({ dsn: "___PUBLIC_DSN___", - // ___PRODUCT_OPTION_START___ profiling - integrations: [ // Add our Profiling integration nodeProfilingIntegration(), ], - // ___PRODUCT_OPTION_END___ profiling - // ___PRODUCT_OPTION_START___ performance - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for tracing. - // We recommend adjusting this value in production - // Learn more at - // https://docs.sentry.io/platforms/javascript/guides/node/configuration/options/#tracesSampleRate + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ profiling - // Enable profiling for a percentage of sessions - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#profileSessionSampleRate + // Enables Profiling for every session. profileSessionSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ profiling }); ``` diff --git a/platform-includes/getting-started-config/python.mdx b/platform-includes/getting-started-config/python.mdx index 9d0c41de4ebc48..60be9c2943b00b 100644 --- a/platform-includes/getting-started-config/python.mdx +++ b/platform-includes/getting-started-config/python.mdx @@ -7,9 +7,10 @@ import sentry_sdk sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. diff --git a/platform-includes/getting-started-config/python.splitlayout.mdx b/platform-includes/getting-started-config/python.splitlayout.mdx index f418645f7aa346..10ba4d9fecbdf1 100644 --- a/platform-includes/getting-started-config/python.splitlayout.mdx +++ b/platform-includes/getting-started-config/python.splitlayout.mdx @@ -6,9 +6,10 @@ from sentry_sdk import metrics sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add data like request headers and IP for users, if applicable; - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # ___PRODUCT_OPTION_START___ performance # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. diff --git a/platform-includes/getting-started-install/javascript.mdx b/platform-includes/getting-started-install/javascript.mdx index bb50e9730ce62f..088d66987dda24 100644 --- a/platform-includes/getting-started-install/javascript.mdx +++ b/platform-includes/getting-started-install/javascript.mdx @@ -20,12 +20,11 @@ pnpm add @sentry/browser In Sentry, go to **Settings > Projects > (select project) > SDK Setup > [Loader Script](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/:projectId/loader-script/)**. -Enable the features you want (for example, Tracing or Session Replay), copy the script tag, and place it before all other scripts in your app. +Enable Tracing, Session Replay, Logs and Metrics, and User Feedback. Then, copy the script tag and place it before all other scripts in your app. #### Option 3: CDN Bundle -Sentry provides different bundles that include specific feature combinations. Go to our list of [available bundles](/platforms/javascript/install/loader/#cdn) and copy the one that fits your needs. -Next, place the script tag before all other scripts in your app. +Sentry provides bundles with different feature combinations. In this guide, we'll use the [full bundle with all features](/platforms/javascript/install/loader/#full-bundle-with-all-features). Copy the script tag and place it before all other scripts in your app. If you're updating your Sentry SDK to the latest version, check out our diff --git a/platform-includes/getting-started-install/javascript.node.mdx b/platform-includes/getting-started-install/javascript.node.mdx index d0c4e2e1614664..36392fd8f473a0 100644 --- a/platform-includes/getting-started-install/javascript.node.mdx +++ b/platform-includes/getting-started-install/javascript.node.mdx @@ -1,21 +1,3 @@ - - -```bash {tabTitle:npm} -npm install @sentry/node -``` - -```bash {tabTitle:yarn} -yarn add @sentry/node -``` - -```bash {tabTitle:pnpm} -pnpm add @sentry/node -``` - - - - - ```bash {tabTitle:npm} npm install @sentry/node @sentry/profiling-node --save ``` @@ -27,5 +9,3 @@ yarn add @sentry/node @sentry/profiling-node ```bash {tabTitle:pnpm} pnpm add @sentry/node @sentry/profiling-node ``` - - diff --git a/platform-includes/getting-started-logs/javascript.mdx b/platform-includes/getting-started-logs/javascript.mdx new file mode 100644 index 00000000000000..36d41f2a986c9d --- /dev/null +++ b/platform-includes/getting-started-logs/javascript.mdx @@ -0,0 +1,16 @@ +Use `Sentry.logger` to send logs at different levels, such as `info`, `warn`, or `error`. You can pass any attributes you want and search or filter by them later. +See Set Up Logs for all available logging methods and the syntax for formatting messages. + +```javascript +Sentry.logger.info("User example action completed"); + +Sentry.logger.warn("Slow operation detected", { + operation: "data_fetch", + duration: 3500, +}); + +Sentry.logger.error("Validation failed", { + form_field: "email", + reason: "Invalid email", +}); +``` diff --git a/platform-includes/getting-started-metrics/javascript.mdx b/platform-includes/getting-started-metrics/javascript.mdx new file mode 100644 index 00000000000000..1b54adb67bdf38 --- /dev/null +++ b/platform-includes/getting-started-metrics/javascript.mdx @@ -0,0 +1,13 @@ +Use `Sentry.metrics` to send counters, gauges, and distributions from your app to Sentry. You can pass any attributes you want and search or filter by them later. +See Set Up Metrics for all available metric types and configuration options. + +```javascript +Sentry.metrics.count("checkout.failed", 1); + +Sentry.metrics.gauge("time_since_refresh", 4, { unit: "hour" }); + +Sentry.metrics.distribution("api_latency", 187, { + unit: "millisecond", + attributes: { endpoint: "/api/orders" }, +}); +``` diff --git a/platform-includes/getting-started-node/javascript.mdx b/platform-includes/getting-started-node/javascript.mdx index 6b1a0e27256a2c..6494a33f2dd079 100644 --- a/platform-includes/getting-started-node/javascript.mdx +++ b/platform-includes/getting-started-node/javascript.mdx @@ -4,25 +4,24 @@ ## Install -Choose the features you want to configure, and this guide will show you how: - - - - - -### Install the Sentry SDK - Run the command for your preferred package manager to add the Sentry SDK to your application: ## Configure +**Error Monitoring** starts working as soon as you call `Sentry.init()`. **Logs** and **Application Metrics** need no extra configuration, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing** and **Profiling**. + + + ### Initialize the Sentry SDK -To import and initialize Sentry, create a file named `instrument.(js|mjs)` in the root directory of your project and add the following code: +To import and initialize Sentry, create a file named `instrument.(js|mjs)` in the root directory of your project and add the code shown below. + +The snippet also turns on: +- Tracing: via `tracesSampleRate` +- Profiling: via `profileSessionSampleRate` and `nodeProfilingIntegration()` @@ -40,14 +39,29 @@ If you are using a bundler like vite, you can also -### Add Readable Stack Traces With Source Maps (Optional) +### Add Readable Stack Traces With Source Maps -### Control the Data You Send to Sentry (Optional) +### Control the Data You Send to Sentry +## Send Logs + + + +If you're already logging with another library, use an integration to capture those logs as Sentry Logs automatically: +- `consoleLoggingIntegration` for `console` calls +- Consola +- Pino + +## Send Application Metrics + + + +On Node.js, `nodeRuntimeMetricsIntegration` also collects runtime health metrics automatically. + ## Verify Your Setup Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. @@ -62,16 +76,11 @@ Finally, head over to your project on [Sentry.io](https://sentry.io/) to view th ## Next Steps -At this point, you should have integrated Sentry into your application, which should already be sending data to your Sentry project. - -Now's a good time to customize your setup and look into more advanced topics. -Our next recommended steps for you are: +At this point, you should have integrated Sentry into your Nest.js application. Here's what to explore next: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup - Extend Sentry to your frontend using one of our [frontend SDKs](/) -- Learn how to manually capture errors -- Continue to customize your configuration -- Get familiar with [Sentry's product features](/product/) like tracing, insights, and alerts +- Set up Agent Tracing to monitor your AI systems diff --git a/platform-includes/getting-started-verify/javascript.express.mdx b/platform-includes/getting-started-verify/javascript.express.mdx index 8b44eea1585994..912a0045585aab 100644 --- a/platform-includes/getting-started-verify/javascript.express.mdx +++ b/platform-includes/getting-started-verify/javascript.express.mdx @@ -1,40 +1,7 @@ -### Issues - -First, let's make sure Sentry is correctly capturing errors and creating issues in your project. Add the following code snippet to your main application file; it defines a route that will deliberately trigger an error when called: +Add an intentional error to your main application file that Sentry will capture: ```javascript app.get("/debug-sentry", function mainHandler(req, res) { throw new Error("My first Sentry error!"); }); ``` - - - -### Tracing - -To test your tracing configuration, update the previous code snippet by starting a trace to measure the time it takes for the execution of your code: - -```javascript -app.get("/debug-sentry", async (req, res) => { - await Sentry.startSpan( - { - op: "test", - name: "My First Test Transaction", - }, - async () => { - await new Promise((resolve) => setTimeout(resolve, 100)); - throw new Error("My first Sentry error!"); - } - ); -}); -``` - - - - - - - - - - diff --git a/platform-includes/getting-started-verify/javascript.fastify.mdx b/platform-includes/getting-started-verify/javascript.fastify.mdx index 32b69ad9f29d89..912a0045585aab 100644 --- a/platform-includes/getting-started-verify/javascript.fastify.mdx +++ b/platform-includes/getting-started-verify/javascript.fastify.mdx @@ -1,40 +1,7 @@ -### Issues - -First, let's make sure Sentry is correctly capturing errors and creating issues in your project. Add the following code snippet to your main application file; it defines a route that will deliberately trigger an error when called: +Add an intentional error to your main application file that Sentry will capture: ```javascript app.get("/debug-sentry", function mainHandler(req, res) { throw new Error("My first Sentry error!"); }); ``` - - - -### Tracing - -To test your tracing configuration, update the previous code snippet by starting a trace to measure the time it takes for the execution of your code: - -```javascript -app.get("/debug-sentry", async (request, reply) => { - await Sentry.startSpan( - { - op: "test", - name: "My First Test Transaction", - }, - async () => { - await new Promise((resolve) => setTimeout(resolve, 100)); // Wait for 100ms - throw new Error("My first Sentry error!"); - } - ); -}); -``` - - - - - - - - - - diff --git a/platform-includes/getting-started-verify/javascript.hapi.mdx b/platform-includes/getting-started-verify/javascript.hapi.mdx index 7502f98762e10b..403e85ec1969c1 100644 --- a/platform-includes/getting-started-verify/javascript.hapi.mdx +++ b/platform-includes/getting-started-verify/javascript.hapi.mdx @@ -1,6 +1,4 @@ -### Issues - -First, let's make sure Sentry is correctly capturing errors and creating issues in your project. Add the following code snippet to your main application file; it defines a route that will deliberately trigger an error when called: +Add an intentional error to your main application file that Sentry will capture: ```javascript server.route({ @@ -11,38 +9,3 @@ server.route({ }, }); ``` - - - -### Tracing - -To test your tracing configuration, update the previous code snippet by starting a trace to measure the time it takes for the execution of your code: - -```javascript -server.route({ - method: "GET", - path: "/debug-sentry", - handler: async (request, h) => { - await Sentry.startSpan( - { - op: "test", - name: "My First Test Transaction", - }, - async () => { - await new Promise((resolve) => setTimeout(resolve, 100)); - throw new Error("My first Sentry error!"); - } - ); - }, -}); -``` - - - - - - - - - - diff --git a/platform-includes/getting-started-verify/javascript.koa.mdx b/platform-includes/getting-started-verify/javascript.koa.mdx index 00cf86c1613853..41bc1d62282484 100644 --- a/platform-includes/getting-started-verify/javascript.koa.mdx +++ b/platform-includes/getting-started-verify/javascript.koa.mdx @@ -1,6 +1,4 @@ -### Issues - -To check that Sentry captures errors, add this middleware before your other middleware in your main application file. Then visit `/debug-sentry` to trigger a test error: +Add this middleware before your other middleware in your main application file. Then visit `/debug-sentry` to trigger a test error: ```javascript app.use(async (ctx, next) => { @@ -10,38 +8,3 @@ app.use(async (ctx, next) => { await next(); }); ``` - - -### Tracing - -To test your tracing configuration, update the previous code snippet by starting a trace to measure the time it takes for the execution of your code: - -```javascript -app.use(async (ctx, next) => { - if (ctx.path !== "/debug-sentry") { - await next(); - return; - } - - await Sentry.startSpan( - { - op: "test", - name: "My First Test Transaction", - }, - async () => { - await new Promise((resolve) => setTimeout(resolve, 100)); - throw new Error("My first Sentry error!"); - } - ); -}); -``` - - - - - - - - - - diff --git a/platform-includes/getting-started-verify/javascript.node.mdx b/platform-includes/getting-started-verify/javascript.node.mdx index dd3623dd571e77..736f01a4579884 100644 --- a/platform-includes/getting-started-verify/javascript.node.mdx +++ b/platform-includes/getting-started-verify/javascript.node.mdx @@ -1,6 +1,4 @@ -### Issues - -First, let's verify that Sentry captures errors and creates issues in your Sentry project. Add the following code snippet to your main application file, which will call an undefined function, triggering an error that Sentry will capture: +Add an intentional error to your main application file that Sentry will capture: ```javascript setTimeout(() => { @@ -11,36 +9,3 @@ setTimeout(() => { } }, 99); ``` - - -### Tracing - -To test your tracing configuration, update the previous code snippet by starting a performance trace to measure the time it takes for the execution of your code: - -```javascript -Sentry.startSpan( - { - op: "test", - name: "My First Test Transaction", - }, - () => { - setTimeout(() => { - try { - foo(); - } catch (e) { - Sentry.captureException(e); - } - }, 99); - } -); -``` - - - - - - - - - - diff --git a/platform-includes/getting-started-verify/ruby.mdx b/platform-includes/getting-started-verify/ruby.mdx index 8f71d92b5981f0..3dcf8a9e7b5549 100644 --- a/platform-includes/getting-started-verify/ruby.mdx +++ b/platform-includes/getting-started-verify/ruby.mdx @@ -39,6 +39,12 @@ To verify that Sentry catches your logs, add some log statements to your applica Use Sentry's Ruby stdlib Logger integration to capture logs from all loggers that use Ruby Logger automatically. + + +Rails structured logging is disabled by default. Set `config.rails.structured_logging.enabled = true` to capture Rails framework events, such as ActiveRecord queries and controller actions. + + + ```ruby Sentry.logger.info("This is an info log message") diff --git a/platform-includes/performance/opentelemetry-setup/python.mdx b/platform-includes/performance/opentelemetry-setup/python.mdx index 4cf61176c17009..e14c203bc291ab 100644 --- a/platform-includes/performance/opentelemetry-setup/python.mdx +++ b/platform-includes/performance/opentelemetry-setup/python.mdx @@ -6,9 +6,10 @@ import sentry_sdk sentry_sdk.init( dsn="___PUBLIC_DSN___", - # Add request headers and IP for users, - # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info - send_default_pii=True, + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, # Set traces_sample_rate to 1.0 to capture 100% # of transactions for tracing. traces_sample_rate=1.0, diff --git a/platform-includes/sentry-init/install-command/javascript.react-router.mdx b/platform-includes/sentry-init/install-command/javascript.react-router.mdx index 18b0452388fa39..923a812e3b83e0 100644 --- a/platform-includes/sentry-init/install-command/javascript.react-router.mdx +++ b/platform-includes/sentry-init/install-command/javascript.react-router.mdx @@ -1,6 +1,6 @@ Run the Sentry init command in your project directory to automatically configure Sentry in your React Router v7 Framework Mode application. -The command guides you through setup and asks which optional Sentry features you want to enable beyond error monitoring. +The command guides you through setup and asks which optional Sentry features you want to enable beyond error monitoring. **Logs** and **Application Metrics** need no extra configuration, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). ```bash npx sentry@latest init diff --git a/redirects.js b/redirects.js index 7e728c5e523889..5d7fecaad69f55 100644 --- a/redirects.js +++ b/redirects.js @@ -2173,14 +2173,6 @@ const userDocsRedirects = [ source: '/product/explore/logs/:path*', destination: '/product/logs/:path*', }, - { - source: '/product/explore', - destination: '/product/trace-explorer/', - }, - { - source: '/product/explore/', - destination: '/product/trace-explorer/', - }, { source: '/platforms/javascript/best-practices/browser-extensions/', destination: '/platforms/javascript/best-practices/shared-environments/', diff --git a/scripts/generate-llms-txt.mjs b/scripts/generate-llms-txt.mjs index 4ffb7f92778eb7..86438e4124ce2e 100644 --- a/scripts/generate-llms-txt.mjs +++ b/scripts/generate-llms-txt.mjs @@ -3,11 +3,13 @@ /** * Generates /llms.txt and /index.md from public/doctree.json. * - * Both files share the same content (product description, AI instructions, - * section listings, agent skills). The only difference is how platforms and - * frameworks are formatted: - * - llms.txt: compact (frameworks listed inline per platform) - * - index.md: expanded (separate Platforms and Frameworks sections) + * Both files share the same body: product description, AI instructions, + * platforms and frameworks, and the doc sections listed for agents. + * index.md adds YAML frontmatter for the Markdown export. + * + * Platforms with a guides/ directory list those guides as frameworks. + * Platforms that document frameworks as integrations (Python, Elixir, and + * any later platform with the same setup) list web frameworks only. * * Run after `generate-doctree` (doctree.json must exist). * Output: @@ -23,12 +25,47 @@ import {mkdir, readFile, writeFile} from 'node:fs/promises'; import * as path from 'node:path'; import {fileURLToPath} from 'node:url'; +import {frameworkNodes} from './platform-frameworks.mjs'; + const __dirname = path.dirname(fileURLToPath(import.meta.url)); const ROOT = path.resolve(__dirname, '..'); const DOCS_ORIGIN = process.env.NEXT_PUBLIC_DEVELOPER_DOCS ? 'https://develop.sentry.dev' : 'https://docs.sentry.io'; +const EXCLUDED_SECTIONS = new Set(['platforms', 'contributing', 'changelog', 'ai']); + +// Titles or descriptions that should stay as written for agents, where they +// differ from the page frontmatter. +const LINK_OVERRIDES = { + pricing: { + title: 'Pricing', + description: + 'Plans, free monthly quotas per feature, trial details, and pay-as-you-go pricing for individual SKUs.', + }, + 'pricing/quotas/spike-protection': { + description: + "Learn how to manage quota and make sure that volume isn't consumed all at once with Spike Protection.", + }, + 'security-legal-pii/scrubbing/server-side-scrubbing': { + title: 'Server Side Scrubbing', + }, +}; + +// Pages nested deeper than the section's first sidebar level. +const EXTRA_PATHS = { + 'security-legal-pii': [ + 'security-legal-pii/scrubbing/server-side-scrubbing', + 'security-legal-pii/security/data-retention-periods', + ], + concepts: ['concepts/key-terms/sample-rates'], +}; + +// Replaces the default child listing. Pricing's own page is not a child of itself. +const ORDERED_PATHS = { + pricing: ['pricing', 'pricing/quotas/spike-protection', 'pricing/quotas'], +}; + // --- Doctree helpers (same logic as generate-md-exports.mjs) --- function getTitle(node) { @@ -52,6 +89,17 @@ function getVisibleChildren(node) { }); } +function findNode(root, nodePath) { + let node = root; + for (const part of nodePath.split('/').filter(Boolean)) { + node = (node.children || []).find(child => child.slug === part); + if (!node) { + return null; + } + } + return node; +} + function mdUrl(nodePath) { const clean = nodePath.replace(/\/$/, ''); if (!clean) { @@ -61,9 +109,10 @@ function mdUrl(nodePath) { } function linkEntry(node) { - const title = getTitle(node); + const override = LINK_OVERRIDES[node.path] || {}; + const title = override.title || getTitle(node); const url = mdUrl(node.path); - const desc = node.frontmatter?.description; + const desc = override.description ?? node.frontmatter?.description; if (desc) { const oneLine = desc.replace(/\s+/g, ' ').trim(); return `- [${title}](${url}): ${oneLine}`; @@ -71,128 +120,104 @@ function linkEntry(node) { return `- [${title}](${url})`; } -// --- Platform/framework formatters --- - -/** llms.txt format: compact, frameworks inline per platform */ -function buildPlatformsCompact(platformsNode) { - if (!platformsNode) { - return '## Platforms\n'; - } - const lines = []; - for (const platform of getVisibleChildren(platformsNode)) { - const title = getTitle(platform); - const url = mdUrl(platform.path); - const guides = platform.children?.find(c => c.slug === 'guides'); - const visibleGuides = guides ? getVisibleChildren(guides) : []; - - if (visibleGuides.length > 0) { - const guideNames = visibleGuides.map(g => getTitle(g)).join(', '); - lines.push(`- [${title}](${url}): Frameworks: ${guideNames}`); - } else { - lines.push(`- [${title}](${url})`); +function resolvePaths(docTree, nodePaths) { + const nodes = []; + for (const nodePath of nodePaths) { + const node = findNode(docTree, nodePath); + if (!node) { + console.warn(`llms.txt: missing doc page ${nodePath}`); + continue; } + nodes.push(node); } - return `## Platforms\n\n${lines.join('\n')}`; + return nodes; } -/** index.md format: separate Platforms list + Frameworks grouped by platform */ +function pagesForSection(section, docTree) { + const ordered = ORDERED_PATHS[section.slug]; + if (ordered) { + return resolvePaths(docTree, ordered); + } + return [ + ...getVisibleChildren(section), + ...resolvePaths(docTree, EXTRA_PATHS[section.slug] || []), + ]; +} + +function buildSectionListings(sections, docTree) { + return sections + .map(section => { + const pages = pagesForSection(section, docTree); + const body = + pages.length > 0 + ? pages.map(page => linkEntry(page)).join('\n') + : linkEntry(section); + return `## ${getTitle(section)}\n\n${body}`; + }) + .join('\n\n'); +} + +function frameworksFor(platform) { + return frameworkNodes(platform, {root: ROOT, visibleChildren: getVisibleChildren}); +} + +/** Separate Platforms list and Frameworks grouped by platform. */ function buildPlatformsExpanded(platformsNode) { if (!platformsNode) { - return '## Platforms\n'; + return '## Platforms'; } const platforms = getVisibleChildren(platformsNode); - const lines = []; - - // Flat platform list - lines.push('## Platforms\n'); + const lines = ['## Platforms', '']; for (const platform of platforms) { lines.push(`- [${getTitle(platform)}](${mdUrl(platform.path)})`); } - // Frameworks grouped by platform - lines.push('\n## Frameworks\n'); + const frameworkBlocks = []; for (const platform of platforms) { - const guides = platform.children?.find(c => c.slug === 'guides'); - const visibleGuides = guides ? getVisibleChildren(guides) : []; - if (visibleGuides.length === 0) { + const frameworks = frameworksFor(platform); + if (frameworks.length === 0) { continue; } - lines.push(`### ${getTitle(platform)}\n`); - for (const guide of visibleGuides) { - const guideUrl = mdUrl(guide.path); - lines.push(`- [${getTitle(guide)}](${guideUrl})`); + const block = [`### ${getTitle(platform)}`, '']; + for (const framework of frameworks) { + block.push(`- [${getTitle(framework)}](${mdUrl(framework.path)})`); } - lines.push(''); + frameworkBlocks.push(block.join('\n')); + } + if (frameworkBlocks.length > 0) { + lines.push('', '## Frameworks', '', frameworkBlocks.join('\n\n')); } - return lines.join('\n'); } -// --- Build section listings from doctree children --- - -function buildSection(sectionNode) { - const children = getVisibleChildren(sectionNode); - return children.map(child => linkEntry(child)).join('\n'); -} - // --- Shared content blocks --- +const SUMMARY = + 'Sentry is an application monitoring platform that helps developers and their agents have the context needed to identify and fix bugs, errors, and performance issues in real-time using a trace-id to create a connected data model across all telemetry.'; + const DESCRIPTION = `\ -> Sentry is a developer-first application monitoring platform that helps \ -developers identify and fix issues in real-time. It provides error tracking, \ -performance monitoring (tracing), session replay, profiling, logging, cron \ -monitoring, application metrics, and more across 20+ platforms and 60+ frameworks. +> ${SUMMARY} + +Key Sentry capabilities include: -All documentation pages are available as clean Markdown by appending \`.md\` \ -to any URL (e.g. \`${DOCS_ORIGIN}/platforms/javascript.md\`). Use these \ -Markdown URLs for full content.`; +- Error tracking groups errors into issues with a human-readable stack trace and context to help developers find the root cause. +- Distributed tracing for capturing the timing and flow of requests and operations as they happen in an application, across the frontend, backend, or agents (Using Sentry's dedicated agent tracing capabilities). Data types that Sentry collects are connected via a common TraceID, and can be used together for debugging issues. For example, when an error happens, spans, logs, replays, and even profiling data can be used in combination to provide highly useful context for an agent or human to investigate that error. +- Structured logs send text-based log information from frontend or backend applications to help with debugging. +- Session replay allows users to watch video-like reproductions of real user sessions that show a timeline of errors, slow span operations, and other issues. +- Profiling provides precise, function-level visibility into where time is being spent in an application. +- Application metrics take counters, gauges, and distributions from application code to track application health and drill down into related traces, logs, and errors, without cardinality blowing up your bill. +- Seer is Sentry's AI debugging tool that detects and diagnoses errors using Sentry data. + +The full list of Sentry features, as well as information on SDKs and pricing, can be found in the Sentry docs (${DOCS_ORIGIN}/index.md). All documentation pages are available as clean Markdown, for example ${DOCS_ORIGIN}/platforms/javascript.md. Use these Markdown URLs for full content.`; const INSTRUCTIONS = `\ -## Instructions for AI Coding Assistants +## For AI Agents When helping a developer set up or use Sentry, follow these guidelines: -- **Install the Sentry plugin for up-to-date guidance**: Sentry's APIs, SDKs, \ -and features change frequently. Do not rely on training data for Sentry setup \ -or configuration. Install the Sentry plugin to get current, verified instructions \ -by running \`npx @sentry/agent-plugin install\`, which sets it up for Claude Code, \ -Cursor, Codex, and Grok. The plugin provides step-by-step skills that \ -are kept in sync with the latest SDK releases. -- **SDK versions**: Always check the package registry (npm, PyPI, RubyGems, \ -etc.) for the latest Sentry SDK version. Do not rely on memorized version \ -numbers from training data. -- **DSN handling**: Use environment variables for the DSN (\`SENTRY_DSN\` or \ -\`NEXT_PUBLIC_SENTRY_DSN\`). Never hardcode DSN strings in source code. -- **Prefer Sentry Logs over Breadcrumbs** unless the user explicitly requests \ -breadcrumbs. -- **Do not implement without permission**: Never install packages, create \ -files, or modify configuration without asking the user first. -- **Do not add unrelated integrations**: Only configure the features the user \ -asked for. Check before enabling additional integrations. -- **Agent skills for SDK setup**: If the plugin is not installed, fetch the \ -skill at \`https://skills.sentry.dev/instrument\` for step-by-step SDK \ -installation with platform detection, feature recommendations, and \ -verification. See the [Agent Plugin section](#agent-plugin) below. -- **Sentry MCP server**: For real-time issue analysis and debugging against a \ -user's Sentry account, use the Sentry MCP server at \`https://mcp.sentry.dev\`.`; - -const AGENT_SKILLS = `\ -## Agent Plugin - -Sentry publishes a plugin for AI coding assistants (Claude Code, Cursor, Codex, \ -and Grok). It teaches the assistant step-by-step SDK setup, debugging \ -workflows, and feature configuration. - -Install it by running \`npx @sentry/agent-plugin install\`, which detects the \ -assistants on the machine and sets up the plugin in each. - -Browse the skill library: -- [All Skills](https://skills.sentry.dev/): Full skill index with SDK setup, workflows, and feature configuration -- [SDK Setup](https://skills.sentry.dev/instrument): Detect your platform and install Sentry with the right features -- [Workflows](https://skills.sentry.dev/workflows): Debug production issues, review code, upgrade SDKs -- [Features](https://skills.sentry.dev/features): AI monitoring, alerts, OpenTelemetry setup - -Source: https://github.com/getsentry/sentry-for-ai`; +- **SDK versions**: Always check the package registry (npm, PyPI, RubyGems, etc.) for the latest Sentry SDK version. Do not rely on memorized version numbers from training data. Get up to date information on SDKs in the docs (${DOCS_ORIGIN}/platforms/) +- **DSN handling**: Use environment variables for the DSN (\`SENTRY_DSN\` or \`NEXT_PUBLIC_SENTRY_DSN\`). +- **Pricing questions**: Don't quote prices or quotas from memory; fetch ${DOCS_ORIGIN}/pricing.md. Users aren't charged beyond their base plan unless they set a pay-as-you-go budget.`; const ABOUT_SENTRY_DOCS = `\ ## About Sentry Docs @@ -218,71 +243,40 @@ async function main() { } const topLevelSections = getVisibleChildren(docTree); - const platformsNode = topLevelSections.find(c => c.slug === 'platforms'); + const platformsNode = topLevelSections.find(child => child.slug === 'platforms'); const otherSections = topLevelSections.filter( - c => c.slug !== 'platforms' && c.slug !== 'contributing' && c.slug !== 'changelog' + child => !EXCLUDED_SECTIONS.has(child.slug) ); + const sectionListings = buildSectionListings(otherSections, docTree); - // Build the shared section listings (everything except platforms) - const sectionListings = otherSections - .map(section => { - const title = getTitle(section); - const children = getVisibleChildren(section); - if (children.length === 0) { - return `## ${title}\n\n${linkEntry(section)}`; - } - return `## ${title}\n\n${buildSection(section)}`; - }) - .join('\n\n'); - - // --- llms.txt --- - const llmsTxt = [ - '# Sentry Documentation', + const body = [ + '# Sentry', '', DESCRIPTION, '', INSTRUCTIONS, '', - buildPlatformsCompact(platformsNode), + buildPlatformsExpanded(platformsNode), '', sectionListings, '', - AGENT_SKILLS, - '', ABOUT_SENTRY_DOCS, '', ].join('\n'); const llmsTxtPath = path.join(ROOT, 'public', 'llms.txt'); - await writeFile(llmsTxtPath, llmsTxt, 'utf8'); - console.log(`Generated ${llmsTxtPath} (${llmsTxt.length} bytes)`); + await writeFile(llmsTxtPath, body, 'utf8'); + console.log(`Generated ${llmsTxtPath} (${body.length} bytes)`); - // --- index.md --- const indexFrontmatter = [ '---', - 'title: "Sentry Documentation"', + `title: ${JSON.stringify('Sentry')}`, + `description: ${JSON.stringify(SUMMARY)}`, `url: ${DOCS_ORIGIN}/`, '---', ].join('\n'); - const indexMd = [ - indexFrontmatter, - '', - '# Sentry Documentation', - '', - DESCRIPTION, - '', - INSTRUCTIONS, - '', - buildPlatformsExpanded(platformsNode), - sectionListings, - '', - AGENT_SKILLS, - '', - ABOUT_SENTRY_DOCS, - '', - ].join('\n'); - + const indexMd = `${indexFrontmatter}\n\n${body}`; const mdExportsDir = path.join(ROOT, 'public', 'md-exports'); if (!existsSync(mdExportsDir)) { await mkdir(mdExportsDir, {recursive: true}); diff --git a/scripts/generate-md-exports.mjs b/scripts/generate-md-exports.mjs index c669a44bd2c642..d2362b5fdf33b3 100644 --- a/scripts/generate-md-exports.mjs +++ b/scripts/generate-md-exports.mjs @@ -1,5 +1,5 @@ #!/usr/bin/env node -/* eslint-disable no-console */ + import {ListObjectsV2Command, PutObjectCommand, S3Client} from '@aws-sdk/client-s3'; import imgLinks from '@pondorasti/remark-img-links'; import {createHash} from 'node:crypto'; @@ -26,6 +26,7 @@ import remarkStringify from 'remark-stringify'; import {unified} from 'unified'; import {remove} from 'unist-util-remove'; +import {frameworkNodes} from './platform-frameworks.mjs'; import {rehypeExpandCodeTabs} from './rehype-expand-code-tabs.mjs'; import {selectMarkdownContent} from './md-export-content.mjs'; import {replaceCurrentUrlTokens} from './markdown-keywords.mjs'; @@ -87,6 +88,7 @@ function applyKeywordDefaults(markdown) { return result; } +const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'); const DOCS_ORIGIN = process.env.NEXT_PUBLIC_DEVELOPER_DOCS ? 'https://develop.sentry.dev' : 'https://docs.sentry.io'; @@ -131,6 +133,10 @@ function getVisibleChildren(node) { }); } +function frameworksFor(platform) { + return frameworkNodes(platform, {root: ROOT, visibleChildren: getVisibleChildren}); +} + function getS3Client() { return new S3Client({ endpoint: 'https://773afa1f62ff86c80db4f24f7ff1e9c8.r2.cloudflarestorage.com', @@ -246,18 +252,14 @@ function buildPlatformsSection(ctx) { const frameworkLines = []; for (const platform of platforms) { - const guidesNode = findNode(platform, ['guides']); - if (!guidesNode) { - continue; - } - const guides = getVisibleChildren(guidesNode); - if (guides.length === 0) { + const frameworks = frameworksFor(platform); + if (frameworks.length === 0) { continue; } frameworkLines.push(`\n### ${getTitle(platform)}\n`); - for (const guide of guides) { + for (const framework of frameworks) { frameworkLines.push( - `- [${getTitle(guide)}](${DOCS_ORIGIN}/platforms/${platform.slug}/guides/${guide.slug}.md)` + `- [${getTitle(framework)}](${DOCS_ORIGIN}/${framework.path}.md)` ); } } @@ -279,7 +281,16 @@ const pageOverrides = [ // Platform index pages (e.g., platforms/javascript.md) match: ctx => ctx.pathParts[0] === 'platforms' && ctx.pathParts.length === 2, sections: [ - {heading: 'Frameworks', items: ctx => nodeLinks(ctx.node, 'guides')}, + { + heading: 'Frameworks', + items: ctx => + ctx.node + ? frameworksFor(ctx.node).map(framework => ({ + title: getTitle(framework), + url: `${DOCS_ORIGIN}/${framework.path}.md`, + })) + : [], + }, {heading: 'Topics', items: ctx => childLinks(ctx, p => !p.includes('/guides/'))}, ], }, @@ -448,12 +459,8 @@ function buildMdxComponents(docTree, createElement) { const platforms = getVisibleChildren(platformsNode); const groups = []; for (const platform of platforms) { - const guidesNode = findNode(platform, ['guides']); - if (!guidesNode) { - continue; - } - const guides = getVisibleChildren(guidesNode); - if (guides.length === 0) { + const frameworks = frameworksFor(platform); + if (frameworks.length === 0) { continue; } groups.push( @@ -461,15 +468,11 @@ function buildMdxComponents(docTree, createElement) { createElement( 'ul', {key: `ul-${platform.slug}`}, - guides.map(g => + frameworks.map(framework => createElement( 'li', - {key: g.slug}, - createElement( - 'a', - {href: `/platforms/${platform.slug}/guides/${g.slug}`}, - getTitle(g) - ) + {key: framework.slug}, + createElement('a', {href: `/${framework.path}`}, getTitle(framework)) ) ) ) diff --git a/scripts/platform-frameworks.mjs b/scripts/platform-frameworks.mjs new file mode 100644 index 00000000000000..65d1ea4f9f7d4b --- /dev/null +++ b/scripts/platform-frameworks.mjs @@ -0,0 +1,91 @@ +/** + * Frameworks listed under each platform in llms.txt, index.md, and platform + * Markdown exports. + * + * Most platforms keep frameworks in platforms//guides/. Python and Elixir + * document them as integrations instead. For those, use the "Web Frameworks" + * section of integrations/index.mdx. Platforms without that section fall back + * to WEB_FRAMEWORK_FALLBACKS. + */ +import {readFileSync} from 'node:fs'; +import * as path from 'node:path'; + +const WEB_FRAMEWORK_FALLBACKS = { + elixir: ['plug_and_phoenix'], +}; + +export function slugsFromWebFrameworksSection(source, platformSlug) { + if (!source) { + return []; + } + const start = source.search(/^### Web Frameworks\s*$/m); + if (start === -1) { + return []; + } + const afterHeading = source.slice(start); + const headingEnd = afterHeading.indexOf('\n'); + const body = afterHeading.slice(headingEnd + 1); + const nextHeading = body.search(/^### /m); + const section = nextHeading === -1 ? body : body.slice(0, nextHeading); + + const slugs = []; + const seen = new Set(); + const urlPattern = new RegExp( + `/platforms/${platformSlug}/integrations/([A-Za-z0-9_-]+)/?`, + 'g' + ); + for (const found of section.matchAll(urlPattern)) { + if (!seen.has(found[1])) { + seen.add(found[1]); + slugs.push(found[1]); + } + } + return slugs; +} + +export function integrationFrameworkSlugs(platformSlug, source) { + const parsed = slugsFromWebFrameworksSection(source, platformSlug); + if (parsed.length > 0) { + return parsed; + } + return WEB_FRAMEWORK_FALLBACKS[platformSlug] ?? []; +} + +function readIntegrationsIndex(root, platformSlug) { + try { + return readFileSync( + path.join(root, 'docs', 'platforms', platformSlug, 'integrations', 'index.mdx'), + 'utf8' + ); + } catch { + return ''; + } +} + +/** + * Visible framework pages for a platform, in docs order. + * Guide-based platforms return their guides. Integration-based platforms + * return web frameworks only. + */ +export function frameworkNodes(platform, {root, visibleChildren}) { + const guides = platform.children?.find(child => child.slug === 'guides'); + const visibleGuides = guides ? visibleChildren(guides) : []; + if (visibleGuides.length > 0) { + return visibleGuides; + } + + if (!platform.frontmatter?.showIntegrationsInSearch) { + return []; + } + + const integrations = platform.children?.find(child => child.slug === 'integrations'); + if (!integrations) { + return []; + } + + const bySlug = new Map(visibleChildren(integrations).map(node => [node.slug, node])); + const source = readIntegrationsIndex(root, platform.slug); + return integrationFrameworkSlugs(platform.slug, source) + .map(slug => bySlug.get(slug)) + .filter(Boolean); +} diff --git a/scripts/platform-frameworks.spec.mjs b/scripts/platform-frameworks.spec.mjs new file mode 100644 index 00000000000000..7a9e3c112f4147 --- /dev/null +++ b/scripts/platform-frameworks.spec.mjs @@ -0,0 +1,94 @@ +import {readFileSync} from 'node:fs'; +import * as path from 'node:path'; +import {fileURLToPath} from 'node:url'; +import {describe, expect, it} from 'vitest'; + +import { + frameworkNodes, + integrationFrameworkSlugs, + slugsFromWebFrameworksSection, +} from './platform-frameworks.mjs'; + +const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'); + +const visibleChildren = node => + (node.children || []).filter(child => child.frontmatter?.title); + +describe('slugsFromWebFrameworksSection', () => { + it('reads the Python Web Frameworks table in page order', () => { + const source = readFileSync( + path.join(root, 'docs/platforms/python/integrations/index.mdx'), + 'utf8' + ); + expect(slugsFromWebFrameworksSection(source, 'python')).toEqual([ + 'django', + 'flask', + 'fastapi', + 'aiohttp', + 'bottle', + 'falcon', + 'pyramid', + 'quart', + 'sanic', + 'starlette', + 'starlite', + 'litestar', + 'tornado', + ]); + }); + + it('stops at the next heading', () => { + const source = [ + '### Web Frameworks', + '', + '[Django](/platforms/python/integrations/django/)', + '', + '### Databases', + '', + '[Redis](/platforms/python/integrations/redis/)', + '', + ].join('\n'); + expect(slugsFromWebFrameworksSection(source, 'python')).toEqual(['django']); + }); +}); + +describe('integrationFrameworkSlugs', () => { + it('uses the Elixir fallback when the page has no Web Frameworks section', () => { + const source = readFileSync( + path.join(root, 'docs/platforms/elixir/integrations/index.mdx'), + 'utf8' + ); + expect(integrationFrameworkSlugs('elixir', source)).toEqual(['plug_and_phoenix']); + }); +}); + +describe('frameworkNodes', () => { + it('prefers guides when a platform has them', () => { + const next = {slug: 'nextjs', frontmatter: {title: 'Next.js'}}; + const platform = { + slug: 'javascript', + frontmatter: {showIntegrationsInSearch: true}, + children: [{slug: 'guides', children: [next]}], + }; + expect(frameworkNodes(platform, {root, visibleChildren})).toEqual([next]); + }); + + it('lists Python web frameworks and skips other integrations', () => { + const platform = { + slug: 'python', + frontmatter: {showIntegrationsInSearch: true}, + children: [ + { + slug: 'integrations', + children: ['django', 'redis', 'flask'].map(slug => ({ + slug, + frontmatter: {title: slug}, + })), + }, + ], + }; + expect( + frameworkNodes(platform, {root, visibleChildren}).map(node => node.slug) + ).toEqual(['django', 'flask']); + }); +}); diff --git a/src/build/resolveOpenAPI.ts b/src/build/resolveOpenAPI.ts index eac8b6ad0c0ae1..1311bd6f119120 100644 --- a/src/build/resolveOpenAPI.ts +++ b/src/build/resolveOpenAPI.ts @@ -6,7 +6,7 @@ import {DeRefedOpenAPI, Parameter} from './open-api/types'; // SENTRY_API_SCHEMA_SHA is used in the sentry-docs GHA workflow in getsentry/sentry-api-schema. // DO NOT change variable name unless you change it in the sentry-docs GHA workflow in getsentry/sentry-api-schema. -const SENTRY_API_SCHEMA_SHA = 'c8e163b204d82a42cb46e9f1c989e39608727b55'; +const SENTRY_API_SCHEMA_SHA = '916a2cd6f0b1a3311ad93e0eeb85c4df8a08374a'; const activeEnv = process.env.GATSBY_ENV || process.env.NODE_ENV || 'development'; diff --git a/src/components/home.tsx b/src/components/home.tsx index 1620eb3c8a3b54..43059e9e1acd3a 100644 --- a/src/components/home.tsx +++ b/src/components/home.tsx @@ -157,7 +157,27 @@ export function Home() { {' '} with one of these agent integrations.

    -
    +
    + } + /> + } + /> + } + /> } /> - } - /> - } - />
    diff --git a/src/components/sidebar/dynamicNav.spec.ts b/src/components/sidebar/dynamicNav.spec.ts new file mode 100644 index 00000000000000..c73099c8ca84be --- /dev/null +++ b/src/components/sidebar/dynamicNav.spec.ts @@ -0,0 +1,37 @@ +import {describe, expect, it, vi} from 'vitest'; + +import type {EntityTree} from './dynamicNav'; +import {getSectionOverviewPath} from './dynamicNav'; + +vi.mock('server-only', () => ({})); + +const entity = (name: string, sidebar_hidden?: boolean): EntityTree => ({ + name, + children: [], + node: { + path: `/platforms/android/${name}/`, + context: {title: name, sidebar_hidden}, + }, +}); + +describe('getSectionOverviewPath', () => { + it('returns the hidden landing page of a section', () => { + expect(getSectionOverviewPath([entity('features', true)], 'features')).toBe( + '/platforms/android/features/' + ); + }); + + it('skips landing pages that already have a sidebar entry', () => { + expect(getSectionOverviewPath([entity('features')], 'features')).toBeNull(); + }); + + it('skips sections without a landing page', () => { + expect(getSectionOverviewPath([entity('tracing', true)], 'features')).toBeNull(); + }); + + it('skips sections that have no landing page configured', () => { + expect( + getSectionOverviewPath([entity('configuration', true)], 'configuration') + ).toBeNull(); + }); +}); diff --git a/src/components/sidebar/dynamicNav.tsx b/src/components/sidebar/dynamicNav.tsx index 8561940f115938..11ca96b6079093 100644 --- a/src/components/sidebar/dynamicNav.tsx +++ b/src/components/sidebar/dynamicNav.tsx @@ -1,4 +1,3 @@ -import Link from 'next/link'; import {Fragment} from 'react'; import {serverContext} from 'sentry-docs/serverContext'; import {sortPages} from 'sentry-docs/utils'; @@ -19,8 +18,9 @@ const SECTION_LABELS: Record = { platform: 'Platform', }; -// Section links configuration - sections that should be clickable headers -const SECTION_LINKS: Record = { +// Sections with a landing page at `//`. When the landing page is +// hidden from the sidebar, an "Overview" link to it becomes the section's first item. +const SECTION_LANDING_PAGES: Record = { features: 'features', }; @@ -100,13 +100,28 @@ export const toTree = (nodeList: Node[]): EntityTree[] => { return result.length > 0 ? result[0].children : []; }; +/** + * Returns the path of a section's landing page if it exists and is hidden from + * the sidebar. Visible landing pages already have their own sidebar entry. + */ +export function getSectionOverviewPath( + children: EntityTree[], + sectionKey: string +): string | null { + const slug = SECTION_LANDING_PAGES[sectionKey]; + if (!slug) { + return null; + } + const landingNode = children.find(child => child.name === slug)?.node; + return landingNode?.context.sidebar_hidden ? landingNode.path : null; +} + export const renderChildren = ( children: EntityTree[], exclude: string[], path: string, showDepth: number = 0, - depth: number = 0, - rootPath?: string + depth: number = 0 ): React.ReactNode[] => { const sortedChildren = sortPages( children.filter( @@ -158,7 +173,7 @@ export const renderChildren = ( isNew={node.context.new} earlyAccess={node.context.early_access} > - {renderChildren(nodeChildren, exclude, path, showDepth, depth + 1, rootPath)} + {renderChildren(nodeChildren, exclude, path, showDepth, depth + 1)} ); @@ -180,32 +195,30 @@ export const renderChildren = ( result.push(); } - // Add section header (with optional link) - const sectionLink = SECTION_LINKS[sectionKey]; - // Check if the section link page actually exists in the tree before creating a link - const sectionPageExists = sectionLink - ? children.some(child => child.name === sectionLink && child.node !== null) - : false; - const sectionHref = - sectionLink && rootPath && sectionPageExists - ? `/${rootPath}/${sectionLink}/` - : null; - result.push(
  • - {sectionHref ? ( - - {SECTION_LABELS[sectionKey]} - - ) : ( - SECTION_LABELS[sectionKey] - )} + {SECTION_LABELS[sectionKey]}
    • ); + const overviewPath = getSectionOverviewPath(children, sectionKey); + if (overviewPath) { + result.push( + + {[]} + + ); + } + // Render items in this section sectionItems.forEach(({node, children: nodeChildren}) => { if (!node) { @@ -223,7 +236,7 @@ export const renderChildren = ( isNew={node.context.new} earlyAccess={node.context.early_access} > - {renderChildren(nodeChildren, exclude, path, showDepth, depth + 1, rootPath)} + {renderChildren(nodeChildren, exclude, path, showDepth, depth + 1)} ); @@ -251,7 +264,7 @@ export const renderChildren = ( isNew={node.context.new} earlyAccess={node.context.early_access} > - {renderChildren(nodeChildren, exclude, path, showDepth, depth + 1, rootPath)} + {renderChildren(nodeChildren, exclude, path, showDepth, depth + 1)} ); }); @@ -264,20 +277,11 @@ type ChildrenProps = { path: string; tree: EntityTree[]; exclude?: string[]; - rootPath?: string; showDepth?: number; }; -export function Children({ - tree, - path, - exclude = [], - showDepth = 0, - rootPath, -}: ChildrenProps) { - return ( - {renderChildren(tree, exclude, path, showDepth, 0, rootPath)} - ); +export function Children({tree, path, exclude = [], showDepth = 0}: ChildrenProps) { + return {renderChildren(tree, exclude, path, showDepth, 0)}; } type Props = { @@ -390,7 +394,6 @@ export function DynamicNav({ exclude={exclude} showDepth={0} path={linkPath} - rootPath={root} />
)} diff --git a/src/data/relay_metrics.json b/src/data/relay_metrics.json index 34771670db9eaa..776411e3fc5235 100644 --- a/src/data/relay_metrics.json +++ b/src/data/relay_metrics.json @@ -381,6 +381,12 @@ "description": "Size of emitted kafka message in bytes.\n\nThis metric is tagged with:\n- `topic`: The Kafka topic being produced to.\n- `variant`: The Kafka message variant.\n- `producer_name`: The configured producer name/deployment identifier.", "features": [] }, + { + "type": "Gauge", + "name": "kafka.reload_generation", + "description": "The number of times this topic's Kafka client has been replaced by a config reload.\n\nArroyo reports the same number\nunder `arroyo.producer.config_reload_generation`; this one is tagged the way Relay tags\nthe rest of its produce metrics, so it lines up with them.\n\nThis metric is tagged with:\n- `topic`: The Kafka topic being produced to.\n- `producer_name`: The configured producer name/deployment identifier.", + "features": [] + }, { "type": "Counter", "name": "logs.envelope", @@ -538,6 +544,18 @@ "processing" ] }, + { + "type": "Counter", + "name": "producer.config_reload.pushed", + "description": "Number of Kafka config blobs handed to a topic's producer.\n\nCounts pushes that were accepted for rollout, which includes blobs that resolve to the\nconfig already running. It does not mean the client was replaced; watch\n[`KafkaGauges::ReloadGeneration`] for that.\n\nThis metric is tagged with:\n- `topic`: The Kafka topic being produced to.\n- `producer_name`: The configured producer name/deployment identifier.", + "features": [] + }, + { + "type": "Counter", + "name": "producer.config_reload.rejected", + "description": "Number of Kafka config blobs a topic's producer refused.\n\nRejection leaves the running client in place. Sustained non-zero values mean this topic\nis no longer applying config changes.\n\nThis metric is tagged with:\n- `topic`: The Kafka topic being produced to.\n- `producer_name`: The configured producer name/deployment identifier.", + "features": [] + }, { "type": "Counter", "name": "producer.enqueue.error",