{"id":18544426,"url":"https://github.com/instructure/inst_statsd","last_synced_at":"2025-04-09T19:30:44.028Z","repository":{"id":56877776,"uuid":"102780842","full_name":"instructure/inst_statsd","owner":"instructure","description":"configurable statsd client proxy","archived":false,"fork":false,"pushed_at":"2025-02-26T15:52:36.000Z","size":175,"stargazers_count":1,"open_issues_count":1,"forks_count":2,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-03-24T10:49:35.206Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/instructure.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-07T20:07:16.000Z","updated_at":"2025-02-26T15:52:39.000Z","dependencies_parsed_at":"2025-01-28T16:30:59.761Z","dependency_job_id":"7add9af7-77f9-484b-95c6-89af7d9388bf","html_url":"https://github.com/instructure/inst_statsd","commit_stats":{"total_commits":51,"total_committers":12,"mean_commits":4.25,"dds":0.6666666666666667,"last_synced_commit":"7d7bfe033614282fae4ffa0675448699e305730e"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/instructure%2Finst_statsd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/instructure%2Finst_statsd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/instructure%2Finst_statsd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/instructure%2Finst_statsd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/instructure","download_url":"https://codeload.github.com/instructure/inst_statsd/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247792899,"owners_count":20996893,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T20:16:29.731Z","updated_at":"2025-04-09T19:30:43.401Z","avatar_url":"https://github.com/instructure.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# InstStatsd\n\nconfigurable statsd client proxy\n\n## Configuration\n\nSet a few enviroment variables:\n\n```bash\nexport INST_STATSD_HOST=statsd.example.org\nexport INST_STATSD_PORT=1234\nexport INST_STATSD_NAMESPACE=my_app.prod\nexport INST_STATSD_APPEND_HOSTNAME=false\nexport INST_DOG_TAGS='{\"app\": \"canvas\", \"env\": \"prod\"}'\n```\n\nOr pass a hash to `InstStatsd.settings`\n\n```ruby\nsettings = {\n  host: 'statsd.example.org'\n  port: 1234\n  namespace: 'my_app.prod'\n  append_hostname: false\n}\n\nInstStatsd.settings = settings\n```\n\nValues passed to `InstStatsd.settings` will be merged into and take precedence over any existing ENV vars\n\n## Configuration Options\n\nFor statsd only the `host` (or `INST_STATSD_HOST` ENV var) is required, all\nother config are optional.\n\nFor data dog, only the `dog_tags` (or `INST_DOG_TAGS` ENV vars) are required.\nAll others are optional. Having `dog_tags` is how to know to use data_dog.\nA `{}` can be passed if you have no desired default tags.\nThe string needs to be parsable as json.\n\n##### `host`\n\nLocation of the statsd box you want to send stats to.\n\n##### `port`\n\nport of the statsd box you want to send stats to.\n\n##### `namespace`\n\nIf a namespace is defined, it'll be prepended to the stat name. So the following:\n\n```ruby\nsettings = {\n  host: 'statsd.example.org'\n  namespace: 'my_app.prod'\n}\n\nInstStatsd.settings = settings\n\nInstStatsd::Statsd.timing('some.stat', 300)\n```\n\nwould use `my_app.prod.some.stat` as it's stat name.\n\n\n##### `append_hostname`\n\nThe hostname of the server will be appended to the stat name, unless\n`append_hostname: false` is specified. So if the namespace is `canvas` and the\nhostname is `app01`, the final stat name of `my_stat` would be\n`canvas.my_stat.app01` (assuming the default statsd/graphite configuration)\n\n##### `dog_tags`\n\nThese are the default tags for the application. Since we do not use the host for\ntags, this allows us to separate different apps and view metrics for one app.\nThe tags are a hash. Example `{app: canvas, environment: production}`\nData dog charges metrics based on unique combination of tags.\n\n## Usage\n\nOutside of configuration, app code generally interacts with the\n`InstStatsd::Statsd` object, which is a proxy class to communicate messages\nto statsd.\n\nAvailable statsd messages are described in:\n\n* [etsty/statsd README](https://github.com/etsy/statsd/blob/master/README.md)\n* [reinh/statsd source](https://github.com/reinh/statsd/blob/master/lib/statsd.rb)\n\nSo for instance:\n\n```ruby\nms = Benchmark.ms { ..code.. }\nInstStatsd::Statsd.timing(\"my_stat\", ms)\n```\n\nIf statsd isn't configured and enabled, then calls to `InstStatsd::Statsd.*`\nwill do nothing and return nil.\n\n\n\n## Default Metrics Tracking\n\nInstStatsd ships with a several trackers that can capture\nseveral performance metrics. To enable these default metrics\ntracking in your rails app, you enable the ones you want, and\nthen enable request tracking:\n\n```ruby\n# config/initializers/inst_statsd.rb\nInstStatsd::DefaultTracking.track_sql\nInstStatsd::DefaultTracking.track_cache\nInstStatsd::DefaultTracking.track_active_record\nInstStatsd::RequestTracking.enable\n```\n\nThis will track the following (as statsd\ntimings) per request:\n\n| Metric Type   | Statsd key                      | Description                               |\n| -----------   | --------------------------      | ---------------------------------         |\n| total         | controller.action.total         | total time spent on controller action*    |\n| db            | controller.action.db            | time spent in the db*                     |\n| view          | controller.action.view          | time spent build views*                   |\n| sql write     | controller.action.sql.write     | number of sql writes                      |\n| sql read      | controller.action.sql.read      | number of sql reads                       |\n| sql cache     | controller.action.sql.cache     | number of sql cache                       |\n| active record | controller.action.active_record | number of ActiveRecord objects created ** |\n| cache read    | controller.action.cache.read    | number of cache reads                     |\n\n\n\\* as reported by [`ActiveSupport::Notifications`](http://api.rubyonrails.org/classes/ActiveSupport/Notifications.html)\n\n\\** as reported by [`aroi`](https://github.com/knomedia/aroi)\n\nIf you'd like InstStatsd to log these metrics (as well as sending them to statsd), pass a logger object along like so:\n\n```ruby\n# log default metrics to environment logs in Rails\nInstStatsd::RequestTracking.enable logger: Rails.logger\n```\n## Block tracking\n\nYou can easily track the performance of any block of code using all enabled\nmetrics. Just be careful that your key isn't too dynamic, causing performance problems\nfor your statsd server.\n\n```ruby\nInstStatsd::DefaultTracking.track_sql\nInstStatsd::DefaultTracking.track_cache\nInstStatsd::DefaultTracking.track_active_record\nInstStatsd::BlockTracking.track(\"my_important_job\") do\n  sleep(10)\nend\n```\n\nIf you want to keep track of both exclusive and inclusive times for a re-entrant piece of code,\nyou just need to tell InstStatsd which category to track along:\n\n```ruby\nInstStatsd::BlockTracking.track(\"my_important_job\", category: :my_stuff) do\n  sleep(10)\n  InstStatsd::BlockTracking.track(\"my_other_important_job\", category: :my_stuff) do\n    sleep(5)\n  end\nend\n```\n\n## Contributing\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create a new Pull Request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finstructure%2Finst_statsd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finstructure%2Finst_statsd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finstructure%2Finst_statsd/lists"}