Write a more complete Custom Instrumentation documentation

[pbernery]

Problem Statement

The https://docs.sentry.io/platforms/ruby/performance/instrumentation/custom-instrumentation/ documentation explains how to track custom transactions. However, it is not complete, calling start_transaction won't be enough, it has to be attached to the current scope.

One correct way to implement custom can be found in the Sentry client code, for instance https://github.com/getsentry/sentry-ruby/blob/6cdb1fc3b1a7f2f10f2783ba27010522d9bf0af5/sentry-rails/lib/sentry/rails/action_cable.rb, where we can see a creation of a scope, then a transaction, and several other things.

I spent many hours understanding why the sample provided in the first documentation did not show up on the Sentry front. I believe the documentation needs to be more complete.

This documentation should also inform about the limit of spans, which can be found on the SDK creation documentation https://develop.sentry.dev/sdk/performance/#maxspans, but is not mentioned on the client documentation.

Solution Brainstorm

No response

Product Area

Performance

[getsantry[bot]]

Assigning to @getsentry/support for routing ⏲️

[getsantry[bot]]

Routing to @getsentry/product-owners-performance for triage ⏲️

[gggritso]

@pbernery thanks for raising this! That's frustrating, sorry about the time waster—we'll take a look at fixing the error you found, and expanding the docs

As for attaching to the current scope, are you adding instrumentation in a threaded environment?

[pbernery]

Hey @gggritso. No I am not, or to be correct, I was not when I implemented my first custom transaction. Now I also have custom transaction tracked in Sidekiq jobs, but now I know how to declare these transactions, it works well.

[sl0thentr0py]

transferring this to docs, will update the custom instrumentation sample. regarding truncation, we'll try to have a page on the product side more transparent about the limits but ultimately these are enforced on the server and can change so it's somewhat hard to keep such lists up to date.

[getsantry[bot]]

Assigning to @getsentry/support for routing ⏲️

[pbernery]

transferring this to docs, will update the custom instrumentation sample. regarding truncation, we'll try to have a page on the product side more transparent about the limits but ultimately these are enforced on the server and can change so it's somewhat hard to keep such lists up to date.

I understand the limitations. I proposed some things here https://github.com/getsentry/sentry-ruby/issues/2307, but still that would depend on the server. Maybe the server could return a status code directly when such content is posted? And thus the client could informed the developer.