# Trifle::Traces

## Navigation
- [Blog](/blog)
  - [Introduction to Trifle Blog](/blog/2022-07-introduction)
  - [Running performance test for Trifle::Stats on your own](/blog/2022-08-running_performance_test_for_stats)
  - [Trifle as an Application Performance Monitoring](/blog/2022-11-performance)
    - [Trifle 01.png](/trifle-01.png)
    - [Trifle 02a.png](/trifle-02a.png)
    - [Trifle 02b.png](/trifle-02b.png)
    - [Trifle 03.png](/trifle-03.png)
    - [Trifle 04a.png](/trifle-04a.png)
    - [Trifle 04b.png](/trifle-04b.png)
    - [Trifle 05.png](/trifle-05.png)
    - [Trifle 06.png](/trifle-06.png)
    - [Trifle 07.png](/trifle-07.png)
  - [Trifle.Stats for Elixir](/blog/2023-06-15-trifle-stats-elixir)
  - [Series data manipulation in Trifle::Stats](/blog/2024-04-series-data-manipulation)
  - [Liveness management in Trifle::Stats](/blog/2025-07-03-beam-and-scan)
- [Robots.txt](/robots.txt)
- [Trifle::Docs](/trifle-docs)
  - [Case Studies](/trifle-docs/case_studies)
    - [Trifle](/trifle-docs/case_studies/trifle)
      - [Inception.png](/inception.png)
    - [Vaclavik](/trifle-docs/case_studies/vaclavik)
      - [Screenshot.png](/screenshot.png)
  - [Changelog](/trifle-docs/changelog)
  - [Configuration](/trifle-docs/configuration)
  - [Folder Structure](/trifle-docs/folder_structure)
    - [Walker](/trifle-docs/folder_structure/walker)
  - [Getting Started](/trifle-docs/getting_started)
    - [Rails with Engine](/trifle-docs/getting_started/rails_with_engine)
    - [Rails with Sinatra](/trifle-docs/getting_started/rails_with_sinatra)
    - [Raw Hardcode Mode](/trifle-docs/getting_started/raw_with_hardcore)
    - [Standalone Sinatra](/trifle-docs/getting_started/standalone_sinatra)
  - [How to Guides](/trifle-docs/guides)
    - [Render Menu](/trifle-docs/guides/menu)
    - [Next & Previous Documents](/trifle-docs/guides/neighbour)
    - [Nested Documents](/trifle-docs/guides/nested)
    - [Table of Content](/trifle-docs/guides/toc)
  - [Harvesters](/trifle-docs/harvesters)
    - [File](/trifle-docs/harvesters/file)
    - [Markdown](/trifle-docs/harvesters/markdown)
  - [Installation](/trifle-docs/installation)
  - [Templates](/trifle-docs/templates)
  - [Usage](/trifle-docs/usage)
- [Trifle::Logs](/trifle-logs)
  - [Case Studies](/trifle-logs/case_studies)
    - [DropBot](/trifle-logs/case_studies/dropbot)
      - [Dropbot Logs.png](/dropbot_logs.png)
  - [Changelog](/trifle-logs/changelog)
  - [Configuration](/trifle-logs/configuration)
  - [Drivers](/trifle-logs/drivers)
    - [File](/trifle-logs/drivers/file)
  - [Formatters](/trifle-logs/formatters)
    - [Json](/trifle-logs/formatters/json)
    - [Text](/trifle-logs/formatters/text)
    - [Timestamp](/trifle-logs/formatters/timestamp)
  - [Getting Started](/trifle-logs/getting_started)
  - [How to Guides](/trifle-logs/guides)
  - [Installation](/trifle-logs/installation)
  - [Result](/trifle-logs/result)
  - [Usage](/trifle-logs/usage)
- [Trifle.Stats](/trifle-stats-ex)
  - [Case Studies](/trifle-stats-ex/case_studies)
  - [Changelog](/trifle-stats-ex/changelog)
  - [Configuration](/trifle-stats-ex/configuration)
  - [Drivers](/trifle-stats-ex/drivers)
    - [Mongo](/trifle-stats-ex/drivers/mongo)
    - [Performance](/trifle-stats-ex/drivers/performance)
  - [Getting Started](/trifle-stats-ex/getting_started)
  - [How to Guides](/trifle-stats-ex/guides)
  - [Installation](/trifle-stats-ex/installation)
  - [Usage](/trifle-stats-ex/usage)
    - [Assert values](/trifle-stats-ex/usage/assert)
    - [Track values](/trifle-stats-ex/usage/track)
    - [Get values](/trifle-stats-ex/usage/values)
- [Trifle::Stats](/trifle-stats-rb)
  - [Aggregators](/trifle-stats-rb/aggregators)
    - [Avg](/trifle-stats-rb/aggregators/avg)
    - [Max](/trifle-stats-rb/aggregators/max)
    - [Min](/trifle-stats-rb/aggregators/min)
    - [Sum](/trifle-stats-rb/aggregators/sum)
  - [Case Studies](/trifle-stats-rb/case_studies)
    - [DropBot](/trifle-stats-rb/case_studies/dropbot)
      - [Daily Source.png](/daily_source.png)
      - [Daily Sqs.png](/daily_sqs.png)
      - [Hourly Calculations1.png](/hourly_calculations1.png)
      - [Hourly Calculations2.png](/hourly_calculations2.png)
  - [Changelog](/trifle-stats-rb/changelog)
  - [Configuration](/trifle-stats-rb/configuration)
  - [Designators](/trifle-stats-rb/designators)
    - [Custom](/trifle-stats-rb/designators/custom)
    - [Geometric](/trifle-stats-rb/designators/geometric)
    - [Linear](/trifle-stats-rb/designators/linear)
  - [Drivers](/trifle-stats-rb/drivers)
    - [Dummy](/trifle-stats-rb/drivers/dummy)
    - [Mongo](/trifle-stats-rb/drivers/mongo)
    - [Performance](/trifle-stats-rb/drivers/performance)
    - [Postgres](/trifle-stats-rb/drivers/postgres)
    - [Process](/trifle-stats-rb/drivers/process)
    - [Redis](/trifle-stats-rb/drivers/redis)
    - [Sqlite](/trifle-stats-rb/drivers/sqlite)
  - [Formatters](/trifle-stats-rb/formatters)
    - [Category](/trifle-stats-rb/formatters/category)
    - [Timeline](/trifle-stats-rb/formatters/timeline)
  - [Getting Started](/trifle-stats-rb/getting_started)
  - [How to Guides](/trifle-stats-rb/guides)
    - [Average](/trifle-stats-rb/guides/average)
    - [Distribution](/trifle-stats-rb/guides/distribution)
    - [Percentiles](/trifle-stats-rb/guides/percentiles)
  - [Installation](/trifle-stats-rb/installation)
  - [Transponders](/trifle-stats-rb/transponders)
    - [Average](/trifle-stats-rb/transponders/average)
    - [Standard Deviation](/trifle-stats-rb/transponders/standard_deviation)
  - [Usage](/trifle-stats-rb/usage)
    - [Assert values](/trifle-stats-rb/usage/assert)
    - [Assort values](/trifle-stats-rb/usage/assort)
    - [Beam values](/trifle-stats-rb/usage/beam)
    - [Scan values](/trifle-stats-rb/usage/scan)
    - [Get series](/trifle-stats-rb/usage/series)
    - [Track values](/trifle-stats-rb/usage/track)
    - [Get values](/trifle-stats-rb/usage/values)
- [Trifle::Traces](/trifle-traces)
  - [Callbacks](/trifle-traces/callbacks)
  - [Case Studies](/trifle-traces/case_studies)
    - [DropBot](/trifle-traces/case_studies/dropbot)
      - [Calculation.png](/calculation.png)
      - [List.png](/list.png)
  - [Changelog](/trifle-traces/changelog)
  - [Configuration](/trifle-traces/configuration)
  - [Getting Started](/trifle-traces/getting_started)
  - [How to Guides](/trifle-traces/guides)
  - [Installation](/trifle-traces/installation)
  - [Middleware](/trifle-traces/middleware)
    - [Rack](/trifle-traces/middleware/rack)
    - [Rails](/trifle-traces/middleware/rails)
    - [Sidekiq](/trifle-traces/middleware/sidekiq)
  - [Serializers](/trifle-traces/serializers)
  - [State](/trifle-traces/state)
  - [Tags and Artifacts](/trifle-traces/tags_and_artifacts)
  - [Usage](/trifle-traces/usage)

## Content
# Trifle::Traces

[![Gem Version](https://badge.fury.io/rb/trifle-traces.svg)](https://rubygems.org/gems/trifle-traces)
[![Ruby](https://github.com/trifle-io/trifle-traces/workflows/Ruby/badge.svg?branch=main)](https://github.com/trifle-io/trifle-traces)

Simple tracer that collects log messages and return values from blocks. And on top of that you can persist in database/storage of your choice.

`Trifle::Traces` is a _way too_ simple timeline tracer that helps you track custom outputs. Ideal for any code from blackbox category (aka background-job-that-talks-to-API-and-works-every-time-when-you-run-it-manually-but-never-when-in-production type of jobs).

## Why?

If you need to track certain execution of a code and log some output, you're pretty much stuck with `Rails::Logger`. That adds bunch of output like timestamp, level and you can even extend it with some additional attributes. Unfortunately that is like using `puts` in 2022.

`Trifle::Traces` helps you to add visibility into parts of your application you never thought you needed (until you did, but then it was too late. Right?). It allows you to use tracer around your code, store text, return values, states and even artifacts all with few simple commands. It does not persist any data, but allows you to choose the storing method that fits your needs the most, all through a series of callbacks.

## Before
You've probably seen code like:

```ruby
require 'rest-client'

module Cron
  class SubmitSomethingWorker
    include Sidekiq::Worker

    def perform(some_id)
      Rails.logger.info "Start processing"
      something = Something.find(some_id)
      Rails.logger.info "Found record in DB"
      body = { code: something.code, count: 100 }
      Rails.logger.info "Sending payload: #{body}"

      RestClient.post('http://example.com/something', body)
      Rails.logger.info "Done?"
    end
  end
end
```

With output like:

```
Start processing
Found record in DB
Sending payload: {code: nil, count: 100}
```

And wondering what went wrong.

## After
Why not rather:

```ruby
require 'rest-client'

module Cron
  class SubmitSomethingWorker
    include Sidekiq::Worker

    def perform(some_id)
      @some_id = some_id
      Trifle::Traces.trace('Sending request') do
        RestClient.post('http://example.com/something', body)
      end
    end

    def body
      Trifle::Traces.trace('Building body') do
        { code: something.code, count: 100 }
      end
    end

    def something
      @something ||= Trifle::Traces.trace('Looking up record in DB') do
        Something.find(@some_id)
      end
    end
  end
end
```
