Ruby SDK Docs not updated with substantial architectural changes

[bmulholland]

SDK

Ruby SDK

Description

Firstly, I already wrote a lot about my confusion about the Ruby SDK over at getsentry/sentry-ruby#2453. I'm coming back to this, filing the docs issue in the right place.

Overall, it seems like the Ruby SDK has made a substantial change in how its expected to be used -- from extra to structured contexts -- and the docs haven't adopted that. In fact, they've dropped the old stuff, about extra, but also not added the new stuff?

Below are additional points of confusion about the docs for the Ruby SDK, from just now:

Beyond what I've raised, here's another specific scenario: I want to log a specific situation to Sentry for investigation. capture_message works for that. I need to include information about the object involved, to dig into that situation. The old syntax was nice: Sentry.capture_message("here's an example of the problem", extra: {problem_object_id: XX})

Now, that's changed. Extra is no longer recommended, and so isn't documented anywhere except a mention in a migration guide. (Which, BTW, the docs Ask AI feature dug up and suggested I use extra, when I asked how to do this thing.) So, okay, deprecated feature, no longer recommended, fine...

But then, the new approach also isn't described anywhere. Nowhere is there a clear spelling of "here's how to attach additional information to a capture_message." Instead, there's conceptual documentation about "structured contexts." It's not clear that this is what's intended to be used together with capture_message, though. It's theoretical and missing steps, and there's little application examples for common scenarios. There's also no "migration guide" for this -- no, "previously, you used extra, like so. Convert that code to this new approach, like so." That would be helpful here. (and clearly would help your AI feature, too)

I just tried to figure out how to convert capture_message to the new approach, and I just now read in a reply to the above message that you can pass a block into the capture_exception? I've scoured https://docs.sentry.io/platforms/ruby and haven't seen that mentioned anywhere -- which continues on my point. The docs are really just missing critical details. And now I want to know if capture_message takes a block too... where can I see that? Especially difficult because there's no SDK reference type docs (like the kind yard generates).

Suggested Solution

No response

[getsantry]

Auto-routing to @getsentry/product-owners-issues for triage ⏲️