Documentation / Recipes / Recipes
Logs tied to the same request
The messages of your Rails app line up with the error they explain, request by request.
When something breaks, the error alone tells you where. The logs written during the same request tell you why: which order, which step, which answer from outside. With the Rails gem, every log carries the identifier of its request, and CloseYourIt puts logs and errors of the same request side by side.
1. Create the project and the token
- In CloseYourIt create a project for the app, for example
shop. - In the project's settings create an ingest token.
- Copy the secret
token, which starts withcyi_, and the project id. Keep the token in the server's environment, never in the code.
2. Install the gem
# Gemfile
gem "closeyourit-ruby"
bundle install
3. Configure it, with the Rails logs
# config/initializers/closeyourit.rb
CloseYourIt.init do |c|
c.endpoint_url = "https://bugs.example.com"
c.token = ENV["CLOSEYOURIT_TOKEN"]
c.project_id = ENV["CLOSEYOURIT_PROJECT_ID"]
c.environment = Rails.env
# Also forward the lines of Rails.logger, from warn up.
c.capture_rails_logs = true
end
Set CLOSEYOURIT_TOKEN and CLOSEYOURIT_PROJECT_ID in the environment of the deployed app, then deploy.
capture_rails_logs forwards only warn and above: at info Rails writes a line for every request and would flood the list. The gem sends nothing from the development and test environments. To try from your computer, add c.disabled_environments = [] and remove it when you are done.
4. Write your own logs
Add messages where the story matters, with the data that explains it:
CloseYourIt.log(:info, "Order created", order_id: order.id, items: order.items.count)
CloseYourIt.log(:warning, "Payment retry", order_id: order.id, attempt: 2)
Inside a request, every message takes the request identifier by itself: the one Rails already assigns. In background jobs the identifier is the job's, so the logs and the error of the same job line up too. You do not have to pass anything.
Messages below info are not sent. Values whose name contains token, email, card or other sensitive words leave the app as [FILTERED].
5. Follow a request
When an error happens in a request that wrote logs:
- Open the error in Errors.
- Open the Logs of this request tab: the messages written while it happened, in order.
- View all logs of this request opens the full list in Logs, filtered on that request.
From a message, the other way round:
- Open Logs and the message.
- This request lists the other logs of the same request, Errors of this request the errors.
You can also paste a request identifier into the search of Logs, or use the terminal:
cyi logs list --trace-id <trace-id>
6. Link a message without the identifier
A message written outside the request, for example by a scheduled script, does not carry the identifier. Link it by hand:
- Open the message.
- In Linked to press Link to error/ticket.
- Search the error by title, then press Link.
The message appears in Linked logs on the error page. You need the "Link a log to a ticket" permission.
How long they are kept
Logs are kept for 14 days, then deleted by themselves. To keep them longer for a project, open it, then Settings and Logs retention (days).