Repository navigation
feat(docs): Apply new quick start template to Rust quick start guides - #19989
sentry-junior[bot] wants to merge 3 commits into
Conversation
Co-Authored-By: Shannon Anahata <shannon.anahata@sentry.io>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
|
The plan checks page loads on the two rewritten guides, client errors on those pages, and sibling guide loads. An issue escalates when those pages stop loading or new client errors appear. Services: Mention PlanWhat changedReaders of the Axum and tracing quick start pages now see the new template. The pages no longer show onboarding option checkboxes. The snippets always include tracing. New sections cover logs and application metrics. RiskA render failure makes those two pages fail in the browser. New code blocks and the metrics badge can raise client errors. Sibling rust guides share the same static generation path. A bad build can drop other rust routes. Users can no longer hide tracing with the old checkboxes. Intended effectThe new headings do not appear in telemetry. Use sampled page loads of the two guide URLs as the proxy. The effect is absent if those URLs drop to zero loads while the rust root page still loads. Traces are sampled at 30 percent. Transaction name is
Regression watchA broken page shows client errors first. Then sampled loads on these URLs fall. Sibling rust routes share generation. Watch the rust root page so a tree-wide drop is visible. Volume is lumpy. Pair every error count with the sampled load count on the same URLs.
If client errors rise, inspect the promise-rejection title on these two URLs first. Then check MDX render of Not observableThe new headings and the removed checkboxes have no content signal. A p75 LCP query on these two URLs returned no rows. Whether tracing stays visible in the snippet is not measured. |
…k start guides Co-Authored-By: Shannon Anahata <shannon.anahata@sentry.io>
## DESCRIBE YOUR PR [sentry-rust 0.49.4](https://github.com/getsentry/sentry-rust/releases/tag/0.49.4) deprecated `sentry::integrations::tracing::layer()`, `SentryLayer`, and `EventFilter`. It replaced them with independently selectable layers, and recommends `SpanLayer` and `LogLayer` for most applications ([getsentry/sentry-rust#1342](getsentry/sentry-rust#1342)). The Rust docs still showed only the deprecated API. - **`tracing` guide**: The example registers `SpanLayer` and `LogLayer` with `LevelFilter::INFO`. I removed the product option toggles because the example no longer depends on them. The page links the API docs for each layer and mentions `ErrorLayer`/`BreadcrumbLayer` as legacy options. It also has a deprecation warning that links the migration guide for the latest 0.49.x release (`~0.49`). The Verify section now covers traces and logs. - **Logs**: Uses `LogLayer` with `LevelFilter::INFO`, and explains in prose why filtering is recommended. - **Automatic instrumentation**: Uses `SpanLayer` with `LevelFilter::INFO`. I compiled and ran the new snippets against `sentry` 0.49.4, with no deprecation warnings. Heads-up: #19989 also edits the `tracing` guide, so one of the two PRs will need a rebase. Resolves #20289 ## IS YOUR CHANGE URGENT? - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: Not urgent, can wait up to 1 week+ ## PRE-MERGE CHECKLIST - [ ] Checked Vercel preview for correctness, including links - [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs) <!-- junior-session-footer:start --> <!-- junior-conversation-id:slack%3AC0CAA8NNBE3%3A1793187164.433919 --> -- [View Junior Session](https://junior-prod.sentry.dev/conversations/slack%3AC0CAA8NNBE3%3A1793187164.433919) [[Sentry]](https://sentry.sentry.io/explore/conversations/slack%3AC0CAA8NNBE3%3A1793187164.433919/?project=4510944073809921) <!-- junior-session-footer:end --> --------- Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com> Co-authored-by: Daniel Szoke <7881302+szokeasaurusrex@users.noreply.github.com>
szokeasaurusrex
left a comment
szokeasaurusrex
left a comment
There was a problem hiding this comment.
Thank you for the changes! I agree some of the content and wording here could use some updating.
That said, I think in some areas, this could be made a bit more concise and less repetitive. I also don't think it is such a good idea to repeat instructions for manual instrumentation of logs and metrics on every page; I would rather we keep that documentation on the pages for those features and only link to those pages if truly necessary.
| **Error Monitoring** starts working as soon as you call `sentry::init()`. **Logs** are supported in Rust SDK 0.42.0 and later and enabled by default. **Application Metrics** are available in Rust SDK 0.48.0 and later; both are covered in [Send Logs](#send-logs) and [Send Application Metrics](#send-application-metrics-). | ||
| This guide also enables **Tracing**. |
There was a problem hiding this comment.
I'm not sure we need to mention all of the different telemetry types here. It could even confuse users, as we shouldn't be capturing logs and metrics without manual instrumentation
| **Error Monitoring** starts working as soon as you call `sentry::init()`. **Logs** are supported in Rust SDK 0.42.0 and later and enabled by default. **Application Metrics** are available in Rust SDK 0.48.0 and later; both are covered in [Send Logs](#send-logs) and [Send Application Metrics](#send-application-metrics-). | ||
| This guide also enables **Tracing**. | ||
|
|
||
| Initialize Sentry before starting the async runtime, then add the Sentry middleware to your Actix Web app. The example route returns an error so you can verify the setup in the next step. |
There was a problem hiding this comment.
Not sure we need this, when we already have the warning below.
| The snippet also turns on: | ||
|
|
||
| - Tracing: via <PlatformLink to="/configuration/options/#traces_sample_rate">`traces_sample_rate`</PlatformLink> and the middleware's `start_transaction(true)`. | ||
| - User IP and HTTP header collection: via <PlatformLink to="/configuration/options/#send_default_pii">`send_default_pii`</PlatformLink>. Review the data your app sends before enabling this in production. | ||
| - HTTP request body collection: via <PlatformLink to="/configuration/options/#max_request_body_size">`max_request_body_size`</PlatformLink>. | ||
|
|
||
| Don't need a feature? Remove its options from the snippet. |
There was a problem hiding this comment.
I would integrate this information into the code comments in the example, otherwise we are duplicating information
| The snippet also turns on: | |
| - Tracing: via <PlatformLink to="/configuration/options/#traces_sample_rate">`traces_sample_rate`</PlatformLink> and the middleware's `start_transaction(true)`. | |
| - User IP and HTTP header collection: via <PlatformLink to="/configuration/options/#send_default_pii">`send_default_pii`</PlatformLink>. Review the data your app sends before enabling this in production. | |
| - HTTP request body collection: via <PlatformLink to="/configuration/options/#max_request_body_size">`max_request_body_size`</PlatformLink>. | |
| Don't need a feature? Remove its options from the snippet. |
| .traces_sample_rate(1.0) | ||
| // Capture user IPs and potentially sensitive headers when using HTTP server integrations | ||
| // see https://docs.sentry.io/platforms/rust/data-management/data-collected for more info | ||
| // Capture user IPs and potentially sensitive headers when using HTTP server integrations. |
There was a problem hiding this comment.
Companion to previous comment
| // Capture user IPs and potentially sensitive headers when using HTTP server integrations. | |
| // Capture user IPs and potentially sensitive headers when using HTTP server integrations. | |
| // Review the data your app sends before enabling this option in production. |
| ### Instrument Actix Web | ||
|
|
||
| The snippet above sets up a service that always fails, so you can test that everything is working as soon as you set it up. | ||
| The Sentry middleware provides correct request and trace association for any captured errors or panics, so it should be the first to process the request. That means it should be the last in your chain of `wrap` calls. | ||
|
|
||
| Send a request to the application. The response error will be captured by Sentry. | ||
| `capture_server_errors(true)` reports server errors returned by your services to Sentry, and `start_transaction(true)` starts a transaction for each request. |
There was a problem hiding this comment.
I find it confusing that this comes after the code sample. It reads as if some additional config is required beyond the sample, but in fact, thecae is already contained there.
There was a problem hiding this comment.
The same comments from the other guides also apply here.
Also, this PR should be rebased on the latest version of the docs, as this guide has been significantly reworked following a redesign of the tracing integration.
| **Error Monitoring** starts working as soon as you call `sentry::init()`. **Logs** are supported in Rust SDK 0.42.0 and later and enabled by default. **Application Metrics** are available in Rust SDK 0.48.0 and later; both are covered in [Send Logs](#send-logs) and [Send Application Metrics](#send-application-metrics-). | ||
| This guide also enables **Tracing**. | ||
|
|
||
| The `sentry::init` function returns a guard that when dropped, will flush Events that weren't yet sent to Sentry. It has a two-second deadline, so application shutdown may be slightly delayed as a result. Be sure to keep the guard or you won't be able to send events. | ||
| Call `sentry::init()` as early as possible in your `main` function. It starts a Sentry client with a default set of integrations, such as panic reporting, and binds it to the current Hub. | ||
|
|
||
| `sentry::init()` returns a guard that flushes events that haven't been sent yet when it's dropped. The flush has a two-second deadline, so application shutdown may be slightly delayed. Keep the guard alive for as long as your app runs, or the SDK won't be able to send events. | ||
|
|
||
| The snippet also turns on: | ||
|
|
||
| - Tracing: via <PlatformLink to="/configuration/options/#traces_sample_rate">`traces_sample_rate`</PlatformLink>. | ||
| - User IP and HTTP header collection: via <PlatformLink to="/configuration/options/#send_default_pii">`send_default_pii`</PlatformLink>. Review the data your app sends before enabling this in production. | ||
|
|
||
| Don't need a feature? Remove its options from the snippet. | ||
|
|
||
| ```rust {filename:main.rs} | ||
| let _guard = sentry::init( | ||
| sentry::ClientOptions::new() | ||
| .dsn("___PUBLIC_DSN___") | ||
| .maybe_release(sentry::release_name!()) | ||
| // Capture user IPs and potentially sensitive headers when using HTTP server integrations | ||
| // see https://docs.sentry.io/platforms/rust/data-management/data-collected for more info | ||
| .send_default_pii(true), | ||
| ); | ||
| fn main() { | ||
| let _guard = sentry::init( | ||
| sentry::ClientOptions::new() | ||
| .dsn("___PUBLIC_DSN___") | ||
| .maybe_release(sentry::release_name!()) | ||
| // Enables Tracing. | ||
| // Set to 1.0 to capture 100% of spans for tracing. | ||
| // We recommend reducing this value in production. | ||
| .traces_sample_rate(1.0) | ||
| // Capture user IPs and potentially sensitive headers when using HTTP server integrations. | ||
| // See https://docs.sentry.io/platforms/rust/data-management/data-collected/ for more info. | ||
| .send_default_pii(true), | ||
| ); | ||
|
|
||
| // implementation of main | ||
| } | ||
| ``` |
There was a problem hiding this comment.
same comments here as from actix
| ## Send Logs | ||
|
|
||
| Use Sentry's `logger_*` macros to send logs at different levels. Logs are supported in Rust SDK 0.42.0 and later and enabled by default unless you compile the SDK without default features. In that case, enable the `logs` feature on `sentry`. For logging through the `tracing` or `log` crates, see the <PlatformLink to="/logs/#tracing-integration">`tracing` integration</PlatformLink> and <PlatformLink to="/logs/#log-integration">`log` integration</PlatformLink> guides. | ||
|
|
||
| See <PlatformLink to="/logs/">Set Up Logs</PlatformLink> for all available logging methods and configuration options. | ||
|
|
||
| ```rust | ||
| use sentry::logger_info; | ||
|
|
||
| logger_info!("Order processed"); | ||
| ``` | ||
|
|
||
| ## Send Application Metrics <FeatureBadge type="new" /> | ||
|
|
||
| - [API Docs](https://docs.rs/sentry) | ||
| - [Crates.io page](https://crates.io/crates/sentry) | ||
| - [Bug Tracker](https://github.com/getsentry/sentry-rust/issues) | ||
| - [GitHub Project](https://github.com/getsentry/sentry-rust) | ||
| Use `sentry::metrics` to send counters, gauges, and distributions. Metrics require Rust SDK 0.48.0 or later and are enabled by default in the `sentry` crate. | ||
|
|
||
| See <PlatformLink to="/metrics/">Set Up Metrics</PlatformLink> for all available metric types and configuration options. | ||
|
|
||
| ```rust | ||
| use sentry::metrics; | ||
|
|
||
| metrics::counter("checkout.failed", 1).capture(); | ||
| metrics::gauge("active_connections", 42).capture(); | ||
| metrics::distribution("api_latency", 187.0).capture(); | ||
| ``` |
There was a problem hiding this comment.
again, not sure if we need to call these out specifically on the main page. We have clear guides for logs and metrics on subpages.
| panic!("Everything is on fire!"); | ||
| ``` | ||
|
|
||
| ### View Captured Data in Sentry |
There was a problem hiding this comment.
| ### View Captured Data in Sentry |
Not sure we need this heading, given how short the section is
| At this point, you should have integrated Sentry into your Rust 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/rust/usage/). | ||
| - Instrument more operations with [custom tracing](/platforms/rust/tracing/instrumentation/custom-instrumentation/). | ||
| - Browse the [API docs](https://docs.rs/sentry), the [crates.io page](https://crates.io/crates/sentry), and the [GitHub project](https://github.com/getsentry/sentry-rust). Report bugs in the [issue tracker](https://github.com/getsentry/sentry-rust/issues). |
There was a problem hiding this comment.
In this section, we might want to also mention that users may wish to enable integrations, as integrations don't get enabled by default in the Rust SDK. I would highlight this before highlighting manual instrumentation.
Remove duplicated telemetry examples and keep verification next to setup code. Retain the redesigned tracing integration while incorporating current master.
|
This PR is too large for Bugbot to review. It changes 41,288 lines and 3,309,497 characters. Split the change into smaller pull requests to get a review. |
DESCRIBE YOUR PR
Applies the quick start template from #19295 (Ember) to the Rust quick starts: the Rust root page and the Axum, Actix Web and tracing guides. All pages keep their single-column layout.
___PRODUCT_OPTION___markers (Axum and tracing).tracingCargo feature.logsfeature must be added when default features are disabled.tracingandlogcrate integrations) and Send Application Metrics as their own steps, and simplifies Verify.traces_sample_rateto the init snippet. The asyncmainguidance and the Integrations section (including thedebug_imageswarning) move under Configure. Verify is a singlepanic!, and the "More Information" links move to Next Steps.max_request_body_sizein the snippet. Middleware ordering,capture_server_errorsandstart_transactionare explained in an "Instrument Actix Web" section under Configure. Verify is a single request to the failing example route.IS YOUR CHANGE URGENT?
PRE-MERGE CHECKLIST
via shannon.anahata.
--
View Junior Session [Sentry]