Custom Instrumentation

When should I add custom instrumentation?

Add custom instrumentation when traces show significant time in “Controller”, “Job”, or “View” layers. This indicates time falling outside Scout’s default instrumentation.

What are the limits on custom instrumentation?

Scout limits the number of unique metrics to prevent UI performance issues. Do NOT dynamically generate metric names with user-specific data (like user IDs). Use tags or custom context for high-cardinality data instead.

How do I instrument a Ruby method?

class User
  include ScoutApm::Tracer

  def export_activity
    # work here
  end
  instrument_method :export_activity
end

The method appears as User#export_activity in traces.

How do I instrument a Ruby code block?

class User
  include ScoutApm::Tracer

  def generate_report
    self.class.instrument("Reporting", "generate") do
      # work here
    end
  end
end

How do I instrument Python code?

As a decorator:

@scout_apm.api.instrument("Computation")
def process_data():
    # work here

As a context manager with tags:

with scout_apm.api.instrument("Computation") as inst:
    inst.tag("record_count", 100)
    # work here

How do I instrument async Python code?

Use the async_ decorator:

@scout_apm.api.instrument.async_("Computation")
async def process_data():
    # async work here

How do I create custom transactions?

For background jobs or scripts outside web frameworks:

Ruby:

ScoutApm::Transaction.rename("custom/my_script")

Python:

with scout_apm.api.BackgroundTransaction("My Script"):
    # work here

What’s the difference between WebTransaction and BackgroundTransaction?

• WebTransaction: For user-facing requests, appears in the “Web” area
• BackgroundTransaction: For non-user-facing work (cron jobs, etc.), appears in “Background Jobs”