feat(ruby): Add queues, caches and requests modules (#10245)

* feat(ruby): Add queues, caches and requests modules

* Update docs/platforms/ruby/common/performance/instrumentation/custom-instrumentation/caches-module.mdx

Co-authored-by: Anton Pirker <anton.pirker@sentry.io>

---------

Co-authored-by: Anton Pirker <anton.pirker@sentry.io>

Author: sl0thentr0py

docs/platforms/ruby/common/performance/instrumentation/custom-instrumentation/caches-module.mdx

@@ -0,0 +1,88 @@
+---
+title: Instrument Caches
+sidebar_order: 1000
+description: "Learn how to manually instrument your code to use Sentry's Caches module. "
+---
+A cache can be used to speed up data retrieval, thereby improving application performance. Because instead of getting data from a potentially slow data layer, your application will be getting data from memory (in a best case scenario). Caching can speed up read-heavy workloads for applications like Q&A portals, gaming, media sharing, and social networking.
+
+Sentry offers a [cache-monitoring dashboard](https://sentry.io/orgredirect/organizations/:orgslug/insights/caches/) for getting an overview of your application's caches.
+
+To make it possible for Sentry to give you an overview of your cache performance, you'll need to create two spans - one indicating that something is being put into the cache, and a second one indicating that something is being fetched from the cache.
+
+Make sure that there's a transaction running when you create the spans. If you're using a web framework like Rails those transactions will be created for you automatically. See <PlatformLink to='/performance/'>Performance Monitoring</PlatformLink> for more information.
+
+For detailed information about which data can be set, see the [Cache Module Developer Specification](https://develop.sentry.dev/sdk/performance/modules/caches/).
+
+## Manual Instrumentation
+
+Follow the steps below to make sure your Cache related spans end up in Sentry correctly.
+
+### Add Span When Putting Data Into the Cache
+
+1. Set the cache value with whatever cache library you happen to be using.
+2. Wrap the part of your application that uses the cached value with  `Sentry.with_child_span { |span| ... }`
+3. Set `op` to `cache.put`.
+4. Set `cache.item_size` to an integer representing the size of the cached item.
+
+(The steps described above are documented in the snippet.)
+
+```ruby
+key = 'myCacheKey123'
+value = 'The value I want to cache.'
+
+Sentry.with_child_span(op: 'cache.put') do |span|
+  # Set a key in your cache using your custom caching solution
+  my_cache.set(key, value)
+
+  # Describe the cache server you are accessing
+  span.set_data('network.peer.address', 'cache.example.com/supercache')
+  span.set_data('network.peer.port', 9000)
+
+  # Add the key you want to set
+  span.set_data('cache.key', key)
+
+  # Add the size of the value you stored in the cache
+  span.set_data('cache.item_size', value.size)  # Warning: if value is very big this could use lots of memory
+end
+```
+
+
+### Add Span When Retrieving Data From the Cache
+
+1. Fetch the cached value from whatever cache library you happen to be using.
+2. Wrap the part of your application that uses the cached value with  `Sentry.with_child_span { |span| ... }`
+3. Set `op` to `cache.get`.
+4. Set `cache.hit` to a boolean value representing whether the value was successfully fetched from the cache or not.
+5. Set `cache.item_size` to an integer representing the size of the cached item.
+
+(The steps described above are documented in the snippet.)
+
+```ruby
+key = 'myCacheKey123'
+value = nil
+
+Sentry.with_child_span(op: 'cache.get') do |span|
+  # Get a key from your caching solution
+  value = my_cache.get(key)
+
+  # Describe the cache server you are accessing
+  span.set_data('network.peer.address', 'cache.example.com/supercache')
+  span.set_data('network.peer.port', 9000)
+
+  # Add the key you just retrieved from the cache
+  span.set_data('cache.key', key)
+
+  if value
+    # If you retrieved a value, the cache was hit
+    span.set_data('cache.hit', True)
+
+    # Optionally also add the size of the value you retrieved
+    span.set_data('cache.item_size', value.size)
+  else
+    # If you could not retrieve a value, it was a miss
+    span.set_data('cache.hit', False)
+  end
+end
+```
+
+You should now have the right spans in place. Head over to the [Cache dashboard](https://sentry.io/orgredirect/organizations/:orgslug/performance/caches/) to see how your cache is performing.

docs/platforms/ruby/common/performance/instrumentation/custom-instrumentation.mdx renamed to docs/platforms/ruby/common/performance/instrumentation/custom-instrumentation/index.mdx

@@ -0,0 +1,91 @@
+---
+title: Instrument Queues
+sidebar_order: 3000
+description: "Learn how to manually instrument your code to use Sentry's Queues module. "
+---
+Sentry comes with automatic instrumentation for the most common messaging queue systems. In case yours isn't supported, you can still instrument custom spans and transactions around your queue producers and consumers to ensure that you have performance data about your messaging queues.
+
+## Producer Instrumentation
+
+To start capturing performance metrics, use the `Sentry.with_child_span` function to wrap your queue producer events. Your span `op` must be set to `queue.publish`. Include the following span data to enrich your producer spans with queue metrics:
+
+| Data Attribute | Type | Description |
+|:--|:--|:--|
+| `messaging.message.id ` | string | The message identifier |
+| `messaging.destination.name` | string | The queue or topic name |
+| `messaging.message.body.size` | int | Size of the message body in bytes |
+
+Make sure that there's a transaction running when you create the spans. If you're using a web framework like Rails those transactions will be created for you automatically. See <PlatformLink to='/performance/'>Performance Monitoring</PlatformLink> for more information.
+
+You must also include the trace propagation headers (`sentry-trace` and `baggage`) using the `Sentry.get_trace_propagation_headers` helper in your message so that your consumers can continue your trace once your message is picked up.
+
+```ruby
+connection = my_custom_queue.connect
+
+# The message you want to send to the queue
+queue = 'messages'
+message = 'Hello World!'
+message_id = 'abc123'
+
+Sentry.with_child_span(op: 'queue.publish', description: 'queue_producer') do |span|
+  # Set span data
+  span.set_data('messaging.message.id', message_id)
+  span.set_data('messaging.destination.name', queue)
+  span.set_data('messaging.message.body.size', message.size)
+
+  # Publish the message to the queue (including trace information and current timestamp)
+  connection.publish(
+    queue: queue,
+    body: message,
+    timestamp: Time.now.utc,
+    headers: Sentry.get_trace_propagation_headers
+  )
+end
+```
+
+## Consumer Instrumentation
+
+To start capturing performance metrics, use the `Sentry.with_child_span` function to wrap your queue consumers. Your span `op` must be set to `queue.process`. Include the following span data to enrich your consumer spans with queue metrics:
+
+| Data Attribute | Type | Description |
+|:--|:--|:--|
+| `messaging.message.id ` | string | The message identifier |
+| `messaging.destination.name` | string | The queue or topic name |
+| `messaging.message.body.size` | number | Size of the message body in bytes |
+| `messaging.message.retry.count ` | number | The number of times a message was attempted to be processed |
+| `messaging.message.receive.latency ` | number | The time in milliseconds that a message awaited processing in queue |
+
+Use `Sentry.continue_trace(trace_propagation_headers)` to start a transaction and connect your consumer spans to their associated producer spans, and `span.set_status` to mark the trace of your message as success or failed.
+
+```ruby
+connection = my_custom_queue.connect
+
+# Pick up message from queues
+queue = 'messages'
+message = connection.consume(queue: queue)
+
+# Calculate latency (optional, but valuable)
+now = Time.now.utc
+message_time = Time.new(message[:timestamp])
+latency = now - message_time
+
+# Continue the trace started in the producer and start a transaction
+transaction = sentry_sdk.continue_trace(message[:headers], op: 'function', name: 'queue_consumer_transaction')
+Sentry.start_transaction(transaction)
+Sentry.get_current_scope.set_span(transaction)
+
+# Start the queue.process span
+Sentry.with_child_span(op: 'queue.process', description: 'queue_consumer') do |span|
+  # Set span data
+  span.set_data('messaging.message.id', message[:message_id])
+  span.set_data('messaging.destination.name', queue)
+  span.set_data('messaging.message.body.size', message[:body].size)
+  span.set_data('messaging.message.receive.latency', latency)
+  span.set_data('messaging.message.retry.count', 0)
+
+  process_message(message)
+rescue
+  # In case of an error set the status to 'internal_error'
+  span.set_status('internal_error')
+end
+```

docs/platforms/ruby/common/performance/instrumentation/custom-instrumentation/queues-module.mdx

@@ -0,0 +1,40 @@
+---
+title: Instrument HTTP Requests
+sidebar_order: 2000
+description: "Learn how to manually instrument your code to use Sentry's Requests module."
+---
+
+As a prerequisite to setting up [Requests](/product/performance/requests/), you’ll need to first <PlatformLink to='/performance/'>set up performance monitoring</PlatformLink>. Once this is done, the Ruby SDK will automatically instrument outgoing HTTP requests made via `Net::HTTP`. If that doesn't fit your use case, you can set up using [custom instrumentation](#custom-instrumentation).
+
+## Custom Instrumentation
+
+For detailed information about which data can be set, see the [Requests Module developer specifications](https://develop.sentry.dev/sdk/performance/modules/requests/).
+
+### Wrap HTTP Requests in a Span
+
+NOTE: Refer to [HTTP Span Data Conventions](https://develop.sentry.dev/sdk/performance/span-data-conventions/#http) for a full list of the span data attributes.
+
+Here is an example of an instrumented function that makes HTTP requests:
+
+```ruby
+require 'uri'
+
+def make_request(method, url)
+  Sentry.with_child_span(op: 'http.client', description: "#{method} #{url}") do |span|
+    span.set_data('http.request.method', method)
+
+    parsed_url = URI.parse(url)
+    span.set_data('url', url)
+    span.set_data('server.address', parsed_url.hostname)
+    span.set_data('server.port', parsed_url.port)
+
+    # make your custom HTTP request
+    response = do_request(method: method, url: url)
+
+    span.set_data('http.response.status_code', response.status_code)
+    span.set_data('http.response_content_length', response.headers['content-length'])
+
+    response
+  end
+end
+```

docs/platforms/ruby/common/performance/instrumentation/custom-instrumentation/requests-module.mdx

@@ -37,5 +37,10 @@ If available, custom instrumentation is documented on an environment-by-environm
 
 - [Python SDK](/platforms/python/performance/instrumentation/custom-instrumentation/caches-module/)
 - [JavaScript SDKs](/platforms/javascript/guides/node/performance/instrumentation/custom-instrumentation/caches-module/)
+- [Laravel SDK](/platforms/php/guides/laravel/performance/instrumentation/custom-instrumentation/)
+- [Java SDK](/platforms/java/performance/instrumentation/custom-instrumentation/)
+- [Ruby SDK](/platforms/ruby/performance/instrumentation/custom-instrumentation/caches-module/)
+- [.NET SDK](/platforms/dotnet/performance/instrumentation/custom-instrumentation/)
+- [Symfony SDK](/platforms/php/guides/symfony/performance/instrumentation/custom-instrumentation/)
 
 To see what cache data can be set on spans, see the [Cache Module Developer Specification](https://develop.sentry.dev/sdk/performance/modules/caches/).

docs/product/performance/caches/index.mdx

@@ -37,6 +37,6 @@ Instructions for custom instrumentation in various languages are linked to below
 - [JavaScript SDK](/platforms/javascript/guides/node/performance/instrumentation/custom-instrumentation/queues-module/)
 - [Laravel SDK](/platforms/php/guides/laravel/performance/instrumentation/custom-instrumentation/)
 - [Java SDK](/platforms/java/distributed-tracing/custom-instrumentation/)
-- [Ruby SDK](/platforms/ruby/)
+- [Ruby SDK](/platforms/ruby/performance/instrumentation/custom-instrumentation/queues-module/)
 - [.NET SDK](/platforms/dotnet/distributed-tracing/custom-instrumentation/)
 - [Symfony SDK](/platforms/php/guides/symfony/distributed-tracing/custom-instrumentation/)

docs/product/performance/queue-monitoring/index.mdx

@@ -1,25 +1,23 @@
 ## Add More Spans to the Transaction
 
-The next example contains the implementation of the hypothetical `process_item` function called from the code snippet in the previous section. Our SDK can determine if there is currently an open transaction and add all newly created spans as child operations to that transaction. Keep in mind that each individual span also needs to be manually finished; otherwise, spans will not show up in the transaction. When using spans and transactions as context managers, they are automatically finished at the end of the `with` block.
-
-You can choose the values of `op` and `description`.
+The next example contains the implementation of the hypothetical `process_item` function called from the code snippet in the previous section. Our SDK can determine if there is currently an open transaction and add all newly created spans as child operations to that transaction. You can choose the values of `op` and `description`.
 
 ```ruby
 class OrdersController < ApplicationController
   def create
     order = Order.new
 
-    Sentry.with_child_span(op: :process_items, description: "") do |span|
-      span.set_data(:key, "value")
+    Sentry.with_child_span(op: :process_items, description: 'processing items') do |span|
+      span.set_data(:key, 'value')
 
       order.process_items(params)
     end
-  end
+  end # the child span ends with the block
 end
 ```
 
 Your new span will be nested under whichever span is currently
-running, otherwise it will be at the root of the transaction event.
+running on the scope, otherwise it will be at the root of the transaction event.
 
 Alternatively, you can manually grab the current transaction and use
 its `with_child_span` method to always create a top-level span.
@@ -29,8 +27,9 @@ class OrdersController < ApplicationController
   def create
     order = Order.new
     transaction = Sentry.get_current_scope.get_transaction
-    transaction.with_child_span(op: :process_items, description: "process order's items") do |span|
-      span.set_data(:key, "value")
+
+    transaction.with_child_span(op: :process_items, description: 'processing items') do |span|
+      span.set_data(:key, 'value')
       order.process_items(params)
     end # the child span ends with the block
   end

platform-includes/performance/add-spans-example/ruby.mdx

@@ -6,9 +6,13 @@ The following example creates a transaction for a scope that contains an expensi
 # start a transaction
 transaction = Sentry.start_transaction(op: "process_item")
 
+# set the transaction on the scope so children span are attached to this transaction
+Sentry.get_current_scope.set_span(transaction)
+
 # perform the operation
 process_item(args)
 
+
 # finish the transaction, which will send it to Sentry automatically
 transaction.finish
 ```

platform-includes/performance/enable-manual-instrumentation/ruby.mdx

@@ -3,10 +3,11 @@
 In cases where you want to attach Spans to an already ongoing Transaction you can use `Sentry.get_current_scope.get_transaction`. This property will return a `Transaction` in case there is a running Transaction otherwise it returns `nil`.
 
 ```ruby
-transaction = Sentry.get_current_scope.get_transaction || Sentry.start_transaction(name: "task")
+transaction = Sentry.get_current_scope.get_transaction || Sentry.start_transaction(name: 'task')
 
-span = transaction.start_child(op: "operation")
+span = transaction.start_child(op: 'operation')
 # perform the operation
+span.finish
 ```
 
 ## Retrieve the Current Span