{"id":13580069,"url":"https://github.com/HubSpot/BuckyServer","last_synced_at":"2025-04-06T00:30:42.503Z","repository":{"id":10588065,"uuid":"12799302","full_name":"HubSpot/BuckyServer","owner":"HubSpot","description":"Node server that receives metric data over HTTP \u0026 forwards to your service of choice","archived":true,"fork":false,"pushed_at":"2016-04-11T04:55:41.000Z","size":215,"stargazers_count":194,"open_issues_count":14,"forks_count":33,"subscribers_count":175,"default_branch":"master","last_synced_at":"2024-11-05T18:51:56.480Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://github.hubspot.com/bucky","language":"CoffeeScript","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/HubSpot.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}},"created_at":"2013-09-13T02:02:25.000Z","updated_at":"2024-10-06T09:36:45.000Z","dependencies_parsed_at":"2022-09-22T20:11:05.896Z","dependency_job_id":null,"html_url":"https://github.com/HubSpot/BuckyServer","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HubSpot%2FBuckyServer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HubSpot%2FBuckyServer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HubSpot%2FBuckyServer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HubSpot%2FBuckyServer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HubSpot","download_url":"https://codeload.github.com/HubSpot/BuckyServer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247419597,"owners_count":20936009,"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-08-01T15:01:46.820Z","updated_at":"2025-04-06T00:30:42.159Z","avatar_url":"https://github.com/HubSpot.png","language":"CoffeeScript","funding_links":[],"categories":["CoffeeScript"],"sub_categories":[],"readme":"## Bucky Server\n\nBucky uses a Node server to forward the HTTP requests with your monitoring data to\nStatsd/Graphite, OpenTSDB, or whatever other service you'd like.\n\nAlso see the [Bucky Client](http://github.hubspot.com/BuckyClient/).\n\n## Hosting\n\nEverything you need to run Bucky on Heroku or Nodejitsu is included, just update the\n[config file](config/default.yaml) and push to the service of your choice.\n\n### Heroku\n\n```bash\nheroku create\ngit push heroku master\n```\n\n### Nodejitsu\n\n```bash\njitsu deploy\n```\n\nThe jitsu application will ask you for a subdomain to run the service on, and will\nincrement the version of the application whenever you deploy.\n\n### EC2 / Bare Metal\n\nIf you'd rather host Bucky on EC2 directly or on raw hardware, you just need something\nwhich will run `./start.js` in a reliable way.\n\nYou can use environment variables to control runtime options, or put them in your [config file](config/default.yaml)\nin the `server` section.\n\nYou'll need to have [nodejs](http://nodejs.org/) installed.  Anything in the 0.8.x series or above should work\nfine.  We recommend using [nvm](https://github.com/creationix/nvm), as it gives you an extra dimension\nof flexibility, but using your system's package manager should work just as well.\n\n```bash\n# In the project directory:\n\nnpm install\nPORT=3333 APP_ROOT=bucky/ ./start.js\n```\n\nThe `APP_ROOT` (or `config.server.appRoot`) will prefix all endpoints.\n\nBucky will respond to all requests at `/APP_ROOT/v1/health-check`, if you need a health check url.\n\nBucky can be setup to receive data at multiple endpoints, but by default it listens\nto `/APP_ROOT/v1/send` on whichever port you specify.\n\n#### Ubuntu (12.04)\n\n```bash\n# Install nodejs\n# This assumes you're on a 64 bit machine\nwget http://nodejs.org/dist/v0.10.19/node-v0.10.19-linux-x64.tar.gz\ntar xvf node-v0.10.19-linux-x64.tar.gz \nsudo ln -s `pwd`/node-v0.10.19-linux-x64/bin/{node,npm} /usr/local/bin/\n\n# Grab a Bucky release\n# You should use the latest release available at https://github.com/HubSpot/BuckyServer/releases\nwget https://github.com/HubSpot/BuckyServer/archive/v0.3.0.tar.gz -O BuckyServer.tar.gz\ntar xvf BuckyServer.tar.gz\ncd BuckyServer\n\n# Install Bucky\nsudo npm install -g\n\n# Make any config changes by editing /usr/local/lib/node_modules/bucky-server/config/default.yaml\n\n# You can start bucky by running bucky-server\n\n# Add the upstart script so Bucky starts on startup and respawns\nsudo cp init/bucky-server.conf /etc/init/\n\n# Start Bucky with\nsudo start bucky-server\n\n# Log files will appear in /var/log/bucky.log by default\n```\n\nYou can run bucky on a specific port (make sure to open that port in your security group\nif you're using EC2), or you can use a reverse proxy like Nginx or HAProxy to serve it\non the same domain and port as your website, it's up to you.\n\n## Configuring\n\nIf you're not already running a stats collection service, you should take a look at our\n[help doc](http://github.hubspot.com/BuckyServer/getting_started/choosing_a_stats_service/).\n\nMost people will only need to specify [the config](config/default.yaml) they're interested in\nand start up the server.\n\nIf you need more customization, you can write a module:\n\n### Modules\n\nThere are a few of types of modules:\n\n\n- Logger - Use to have Bucky log to something other than the console\n- Config - Use to have Bucky pull config from somewhere other than the default file\n- App - Use to do things when Bucky loads and/or on requests.  Auth, monitoring initialization, etc.\n- Collectors - Use to send Bucky data to new and exciting places.\n\nWe can only have one logger and one config, but you can specify as many app and collector modules\nas you like.\n\nAll modules follow the same basic sketch.  You export a method which is called when Bucky\nstarts up.  That method is provided with as much of `{app, config, logger}` as we have\nloaded so far, and is expected to call a callback when it's ready for the loading to continue.\n\n#### Logger\n\nUsed to log output.  Defaults to a wrapper around console.log/console.error.\n\nShould export a function which will be called when the server is started:\n\n```coffeescript\nmodule.exports = ({logger}, next) -\u003e\n  # logger is the previous logger (just the console)\n\n  next myNewLogger\n```\n\nThis function should call the callback with a logger object which implements\n`log` and `error`:\n\n```coffeescript\nmodule.exports = ({logger}, next) -\u003e\n  myNewLogger = {\n    log: -\u003e\n      console.log \"Bucky message:\", arguments...\n    error: -\u003e\n      console.error \"Bucky error:\", arguments...\n  }\n\n  next myNewLogger\n```\n\n#### Config\n\nBy default config comes from the config files loaded using the node `config` module.\n\nIf specified, this module will replace that config.  Please note that the list of\nmodules comes from the `config` module, so the list of modules must always be\nspecified there.  All other config options can be moved to your config solution\nof choice using this extension point.\n\nAt HubSpot, we're believers in config which can be changed without restarting\nservices. For this reason, the config api is a bit more complex than you might\nexpect.  A wrapper is provided in `lib/configWrapper.coffee` for you to use\nshould you wish to use a simpler solution.\n\n```coffeescript\nmodule.exports = ({config, logger}, next) -\u003e\n  # config is the old config which was being used\n  # before this module was loaded\n\n  # logger.log and logger.error should be used rather than\n  # console\n\n  next myConfigObject\n```\n\nA config value will be retrieved from the config object the callback is\ncalled with like this:\n\n```coffeescript\n  config.get('some.config').get()\n\n  config.get('some.config').on 'change', -\u003e\n    # The config changed!\n```\n\nYou are free to implement the `on` method as a dud if live reloading doesn't\nmake sense using your config system.  Take a look at [lib/configWrapper.coffee](lib/configWrapper.coffee)\nfor an example of how a basic object can be converted (and feel free to use it).\n  \n#### App\n\nApp modules get loaded once, and can optionally provide a function to be ran with each request.\n\nSimple app modules are a good place to put any server config, initialization code, etc.\n\nWe use app modules to make [little tweaks](modules/trustProxy.coffee) to how express works and enable\nmonitoring.\n\nApp modules are called at initialize-time with a hash including a reference to the express app:\n\n```coffeescript\nmodule.exports = ({app, logger, config}, next) -\u003e\n```\n\nIf your app module calls the callback with a function, that function will be executed on all requests to\n`/v1/send`, which is the default endpoint.\n\nIf the callback is called with a hash, it is expected to be a mapping between endpoints and handler functions.\n\n```coffeescript\nmodule.exports = ({app, logger, config}, next) -\u003e\n  next\n    send: (req, res, _next) -\u003e\n      # Standard express request handling stuff in here\n\n    someOtherEndpoint: (req, res, _next) -\u003e\n       # Will get requests which are sent to /v1/someOtherEndpoint\n```\n\nThese functions work like middleware, they are called sequentially.  You can use them to implement\nthings like [auth](modules/auth.coffee) if you need it.\n\n#### Collectors\n\nIt's not a standard type of module (the core of Bucky has no idea about it), but the default\n[collectors app module](modules/collectors.coffee) looks to a fourth type of module to know\nwhere to send data.\n\n[Statsd](modules/statsd.coffee) and [OpenTSDB](modules/openTSDB.coffee) collectors are included.\n\nCollectors should export a function which is called on initialize, and call the callback with a hash\nmapping endpoints to handlers.\n\n```coffeescript\nmodule.exports = ({app, logger, config}, next) -\u003e\n  next\n    send: (data) -\u003e\n      # This collector will receive any requests to /v1/send (the default endpoint)\n\n      logger.log \"We got some data!\"\n```\n\n### Format\n\nIf you are interested in writing new clients, the format of metric data is the same as is used by statsd:\n\n```\n\u003cmetric name\u003e:\u003cmetric value\u003e|\u003cunit\u003e[@\u003csample rate\u003e]\n```\n\nFor example:\n\n```\nmy.awesome.metric:35|ms\nsome.other.metric:3|c@0.5\n```\n\nAll requests are sent with content-type `text/plain`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHubSpot%2FBuckyServer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FHubSpot%2FBuckyServer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHubSpot%2FBuckyServer/lists"}