Skip to content

Latest commit

 

History

History
113 lines (73 loc) · 6.2 KB

index.md

File metadata and controls

113 lines (73 loc) · 6.2 KB
title layout
Home
default

Table of Contents

Progstr » logger is a service that collects and manages programmer log entries in the cloud. Most web applications log errors and special external events generated by users or third party systems. Progstr » logger takes away the pain of complex logging system configurations, provides a centralized location for all your log entries and helps you analyze the data you've collected over time. progstr-ruby is the Ruby client library that collects log entries and transports them to the Progstr data store.

Local Setup

To use the logging API, you need the progstr-ruby gem added to your application. Add it to your bundler configuration by adding this line to your Gemfile:

group :production, :staging do
  gem "progstr-ruby", :require => 'progstr'
end

Of course, don't add a second production or staging group if you already have those in place. In addition, if you wish to only log events in production, register the gem for the production group only. Note that we set up an automatic require for the "progstr" module. If you don't use a Gemfile dependency in that way, you would have to add a require 'progstr' line to your Ruby scripts.

In addition, you might wish to install the progstr-ruby gem on your development system. Tell bundler to do so by running:

bundle install

Next: integrate it in your project.

Configure the API key by setting the Progstr.api_key property before you start logging. Set up Rails, so that it sends logs to the Progstr service by changing your respective environment configuration. For example, add this to your config/environments/production.rb:

# Read the key from the Heroku environment
Progstr.api_key = ENV['PROGSTR_API_KEY']
Progstr::RailsLogger.start config

#Deploying to Heroku

To add progstr » logger to your Heroku application, simply install the Progstr add-on:

$ heroku addons:add progstr:test

This will provision a Progstr account and set the heroku evironment variable PROGSTR_API_KEY with the respective key needed to access the logger API.

Of course, you can also install the add-on from the Heroku web site.

#Using the Logger API

If you configure your Rails app as described above, your application-generated logs will automatically get sent to the Progstr servers. That means that you can watch your controller execution times, your DB queries and all the logs Rails generates by default. In addition you can use the logger API to log your own events specific to your application.

There are four log severity levels that you can use to log events of different importance:

  • Info: used to log general information events that can be used for reference or troubleshooting if needed.
  • Warning: something odd happened and somebody needs to know about it.
  • Error: something failed and needs to be fixed.
  • Fatal: the entire application or a critical part of it is not working at all.

To log an event you need to create a Progstr::Logger object and call some of its info/warn/error/fatal methods. You need to provide the logger source name as a constructor parameter. That will be used to categorize logs and make it easier for you to find specific entries:

require 'progstr'
...
...
home_log = Progstr::Logger.new("HomeController")
...
home_log.info(message);
...
home_log.warn(message);
...
home_log.error(message);
...
home_log.fatal(message);

A Progstr::Logger object is really a standard Ruby Logger. That means you can also check the current log level or do conditional logging using blocks that are evaluated only if the respective level has been enabled. For example, to construct a log message and log it only if info logging has been enabled, you can do this:

home_log.info { "Assemble " + "a complex log message here: #{user.name}" }

Alternatively, you can override the source name by passing the progname parameter to log methods:

home_log.warn("other-source") { "Oops, I need to warn somebody!" }

If you have configured Rails to send all logs to our service, you can simply use the Rails.logger object to log:

Rails.logger.info("HomeController#index called")
# or
Rails.logger.info("HomeController") { "index action called." }

Note: Ruby Logger objects also support debug-level logs. It is not a good idea to enable debug logging in production, and we advise against it. Still, for those moments when you are pulling your hair out, you can enable it by setting the Progstr.log_debug_events option to true in your environment config file.

Viewing logs and setting up alerts

Use your Heroku application page to log in to the progstr » logger control panel and access your logs. You will be able to view log statistics, search for specific logs, set up error alerts and much more.

#Exploring the online sample application

We are running a fully-featured Rails application, hosted on Heroku, logging to a "demo" account at http://rails.progstr.com. It demonstrates several useful logging techniques that you can use in your project too. Play around with it and make sure you access the demo account and view the events that you have just generated.

The full source code for the sample application is available on GitHub.

Supported platforms

  • Ruby 1.8.7 and later
  • Rails 3.0 and later

Documentation

Available online here.

Feedback

  • If you have a feature suggestion, enhancement idea, or a bug report for the client library, please open a ticket on the project issue tracker.
  • For general problems or inquiries regarding integrating the library in your project or the progstr » logger service, please contact support.