{"id":13513723,"url":"https://github.com/HubSpot/BuckyClient","last_synced_at":"2025-03-31T02:32:54.635Z","repository":{"id":10588091,"uuid":"12799336","full_name":"HubSpot/BuckyClient","owner":"HubSpot","description":"Collect performance data from the client","archived":false,"fork":false,"pushed_at":"2016-08-05T20:07:08.000Z","size":671,"stargazers_count":1735,"open_issues_count":19,"forks_count":98,"subscribers_count":210,"default_branch":"master","last_synced_at":"2024-10-19T03:20:14.641Z","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:04:13.000Z","updated_at":"2024-10-18T10:42:08.000Z","dependencies_parsed_at":"2022-08-29T18:51:59.480Z","dependency_job_id":null,"html_url":"https://github.com/HubSpot/BuckyClient","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HubSpot%2FBuckyClient","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HubSpot%2FBuckyClient/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HubSpot%2FBuckyClient/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HubSpot%2FBuckyClient/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HubSpot","download_url":"https://codeload.github.com/HubSpot/BuckyClient/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222615147,"owners_count":17012022,"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-01T05:00:36.565Z","updated_at":"2024-11-01T17:30:38.668Z","avatar_url":"https://github.com/HubSpot.png","language":"CoffeeScript","funding_links":[],"categories":["CoffeeScript"],"sub_categories":[],"readme":"Bucky\n=====\n\nBucky is a client and server for sending performance data from the client into statsd+graphite, OpenTSDB, or any\nother stats aggregator of your choice.\n\nIt can automatically measure how long your pages take to load, how long AJAX requests take and how long\nvarious functions take to run.  Most importantly, it's taking the measurements on actual page loads,\nso the data has the potential to be much more valuable than in vitro measurements.\n\nIf you already use statsd or OpenTSDB, you can get started in just a few minutes.  If you're not\ncollecting stats, you [should start](http://github.hubspot.com/BuckyServer/getting_started/choosing_a_stats_service/)!\nWhat gets measured gets managed.\n\n### Server\n\nYou can play with Bucky just using the client, but if you'd like to start collecting data, see the\n[Server Instructions](http://github.hubspot.com/BuckyServer/).\n\n### Setup\n\n#### From The Client\n\nInclude [bucky.js](https://raw.github.com/HubSpot/BuckyClient/v0.2.3/bucky.min.js) on your page, the only required config can be done right in the script tag:\n\n```html\n\u003cscript src=\"bucky.js\" data-bucky-host=\"/bucky\" data-bucky-page data-bucky-requests\u003e\u003c/script\u003e\n```\n\nThat config will automatically log the performance of your page and all the requests you make to a server running at\n/bucky.  It will automatically decide the right key name based on the url of the page.  If you'd like, you can also specify it manually:\n\n```html\n\u003cscript src=\"bucky.js\" data-bucky-host=\"/bucky\" data-bucky-page=\"index\" data-bucky-requests=\"index\"\u003e\u003c/script\u003e\n```\n\nThe `Bucky` object will be available globally, but there is nothing you need to call for basic usage.\n\nBucky can also be loaded with AMD or Browserify (see the methods below).\n\n#### From Node\n\n```bash\nnpm install bucky\n```\n\n```coffeescript\nbucky = require('bucky')\n```\n\n### Configuring\n\nBefore sending any data, call `setOptions` if you're not using the data- attribute based configuration:\n\n```javascript\nBucky.setOptions({\n  host: 'http://myweb.site:9999/bucky'\n});\n```\n\nSome options you might be interested in:\n\n- `host`: Where we can reach your [Bucky server](http://github.com/HubSpot/BuckyServer), including the\n  APP_ROOT.\n\n  The Bucky server has a very liberal CORS config, so we should be able to connect to it even if\n  it's on a different domain, but hosting it on the same domain and port will save you some preflight requests.\n\n- `active`: Should Bucky actually send data?  Use this to disable Bucky during local dev for example.\n- `sample`: What fraction of clients should actually send data?  Use to subsample your clients if you have\n  too much data coming in.\n\nTake a look at [the source](http://github.com/HubSpot/BuckyClient/blob/master/bucky.coffee#L34) for a\nfull list of options.\n\n#### Sending Page Performance\n\nModern browsers log a bunch of page performance data, bucky includes a method for writing all of this in\none go.  It won't do anything on browsers which don't support the performance.timing api.  Call it whenever,\nit will bind an event if the data isn't ready yet.\n\n```coffeescript\nBucky.sendPagePerformance('where.the.data.should.go')\n```\n\nSetting `data-bucky-page` triggers this automatically.\n\nThe two most relevant stats provided are `responseEnd` which is the amount of time it took for the\noriginal page to be loaded and `domInteractive` which is the amount of time before the page has\nfinished loaded and can be interacted with by the user.\n\nAs a reminder: this data is browser specific, so it will likely skew lower than what users on\nold browsers see.\n\nIf you're using Backbone, it might be a good idea to send your data based on route:\n\n```coffeescript\nBackbone.history.on 'route', (router, route) -\u003e\n   # Will only send on the initial page load:\n   Bucky.sendPagePerformance(\"some.location.page.#{ route }\")\n```\n\nThe data collected will look something like this:\n\n```javascript\npages.contactDetail.timing.connectEnd: \"172.000|ms\"\npages.contactDetail.timing.connectStart: \"106.000|ms\"\npages.contactDetail.timing.domComplete: \"1029.000|ms\"\npages.contactDetail.timing.domContentLoadedEventEnd: \"1019.000|ms\"\npages.contactDetail.timing.domContentLoadedEventStart: \"980.000|ms\"\npages.contactDetail.timing.domInteractive: \"980.000|ms\"\npages.contactDetail.timing.domLoading: \"254.000|ms\"\npages.contactDetail.timing.domainLookupEnd: \"106.000|ms\"\npages.contactDetail.timing.domainLookupStart: \"106.000|ms\"\npages.contactDetail.timing.fetchStart: \"103.000|ms\"\npages.contactDetail.timing.loadEventEnd: \"1030.000|ms\"\npages.contactDetail.timing.loadEventStart: \"1029.000|ms\"\npages.contactDetail.timing.navigationStart: \"0.000|ms\"\npages.contactDetail.timing.requestStart: \"173.000|ms\"\npages.contactDetail.timing.responseEnd: \"243.000|ms\"\npages.contactDetail.timing.responseStart: \"235.000|ms\"\npages.contactDetail.timing.secureConnectionStart: \"106.000|ms\"\n```\n\nA description of what each datapoint represents is included in [the spec](http://www.w3.org/TR/navigation-timing-2/#sec-PerformanceNavigationTiming).\n\n#### Sending AJAX Request Time\n\nBucky can automatically log all ajax requests made by hooking into XMLHttpRequest and doing some transformations\non the url to try and create a graphite key from it.  Enable it as early in your app's load as is possible:\n\n```coffeescript\nBucky.requests.monitor('my.project.requests')\n```\n\nSetting `data-bucky-requests` calls this automatically.\n\nThe data collected will look something like this for a GET request to\n`api.hubapi.com/automation/v2/workflows`:\n\n```javascript\ncontacts.web.prod.requests.api.hubapi.automation.v2.workflows.get: \"656.794|ms\"\ncontacts.web.prod.requests.api.hubapi.automation.v2.workflows.get.2xx: \"1|c\"\ncontacts.web.prod.requests.api.hubapi.automation.v2.workflows.get.200: \"1|c\"\ncontacts.web.prod.requests.api.hubapi.automation.v2.workflows.get.headers: \"436.737|ms\"\ncontacts.web.prod.requests.api.hubapi.automation.v2.workflows.get.receiving: \"0.182|ms\"\ncontacts.web.prod.requests.api.hubapi.automation.v2.workflows.get.sending: \"0.059|ms\"\ncontacts.web.prod.requests.api.hubapi.automation.v2.workflows.get.waiting: \"206.035|ms\"\n```\n\n#### Prefixing\n\nYou can build a client which will prefix all of your datapoints by calling bucky as a function:\n\n```coffeescript\nmyBucky = Bucky('awesome.app.view')\n\n# You can then use all of the normal methods:\nmyBucky.send('data.point', 5)\n```\n\nYou can repeatedly call clients to add more prefixes:\n\n```coffeescript\ncontactsBucky = bucky('contacts')\ncwBucky = contactsBucky('web')\n\ncwBucky.send('x', 1) # Data goes in contacts.web.x\n```\n\n#### Counting Things\n\nBy default `send` sends absolute values, this is rarely what you want when working from the client, incrementing\na counter is usually more helpful:\n\n```coffeescript\nbucky.count('my.awesome.thing')\nbucky.count('number.of.chips.eaten', 5)\n```\n\n#### Timing Things\n\nYou can manually send ms durations using `timer.send`:\n\n```coffeescript\nbucky.timer.send('timed.thing', 55)\n```\n\nBucky includes a method to time async functions:\n\n```coffeescript\nbucky.timer.time 'my.awesome.function', (done) -\u003e\n  asyncThingy -\u003e\n    done()\n```\n\nYou can also manually start and stop your timer:\n\n```coffeescript\nbucky.timer.start 'my.awesome.function'\n\nasyncThingy -\u003e\n  bucky.timer.stop 'my.awesome.function'\n```\n\nYou can time synchronous functions as well:\n\n```coffeescript\nbucky.timer.timeSync 'my.awesome.function', -\u003e\n  Math.sqrt(100)\n```\n\nThe `time` and `timeSync` functions also accept a context and arguments to pass to the \ncalled function:\n\n```coffeescript\nbucky.timer.timeSync 'my.render.function', @render, @, arg1, arg2\n```\n\nYou can wrap existing functions using `wrap`:\n\n```coffeescript\nfunc = bucky.timer.wrap('func.time', func)\n```\n\nIt also supports a special syntax for methods:\n\n```coffeescript\nclass SomeClass\n  render: bucky.timer.wrap('render') -\u003e\n    # Normal render stuff\n```\n\nNote that this wrapping does not play nice with CoffeeScript `super` calls.\n\nBucky also includes a function for measuring the time since the navigationStart event was fired (the beginning of the request):\n\n```coffeescript\nbucky.timer.mark('my.thing.happened')\n```\n\nIt acts like a timer where the start is always navigation start.\n\nThe stopwatch method allows you to begin a timer which can be stopped multiple times:\n\n```coffeescript\nwatch = bucky.stopwatch('some.prefix.if.you.want')\n```\n\nYou can then call `watch.mark('key')` to send the time since the stopwatch started, or\n`watch.split('key')` to send the time since the last split.\n\n### Sending Points\n\nIf you want to send absolute values (rare from the client), you can use send directly.\n\nThe one use we've had for this is sending `+new Date` from every client to get an idea\nof how skewed their clocks are.\n\n```coffeescript\nBucky.send 'my.awesome.datapoint', 2432.43434\n```\n\n### Your Stats\n\nYou can find your stats in the `stats` and `stats.timing` folders in graphite, or as written in OpenTSDB.\n\n### Send Frequency\n\nBucky will send your data in bulk from the client either five seconds after the last datapoint is added, or thirty seconds after\nthe last send, whichever comes first.  If you log multiple datapoints within this send frequency, the points will\nbe averaged (and the appropriate frequency information will be sent to statsd) (with the exception of counters, they\nare incremented).  This means that the max and min numbers you get from statsd actually represent the max and min \n5-30 second bucket.  Note that this is per-client, not for the entire bucky process (it's generally only important\non the server where you might be pushing out many points with the same key).\n\n### Bucky Object\n\nThe Bucky object provides a couple extra properties you can access:\n\n- `Bucky.history`: The history of all datapoints ever sent.\n- `Bucky.active`: Is Bucky sending data?  This can change if you change the `active` or `sample` settings.\n- `Bucky.flush()`: Send the Bucky queue immediately\n- `Bucky.timer.now()`: A clock based on the most precise time available (not guarenteed to be from the epoch)\n\n### URL -\u003e Key Transformation\n\n`request.monitor` attempts to automatically transform your urls into keys.  It does a bunch of transformations\nwith the goal of removing anything which will vary per-request, so you end up with stats per-endpoint.  These\ntranformations include:\n\n- Stripping GUIDS, IDs, SHA1s, MD5s\n- Stripping email addresses\n- Stripping domains\n\nIf you find these tranformations too invasive, or not invasive enough, you can modify them.\n\n```javascript\n// You can diable tranforms with `.disable`\nBucky.requests.transforms.disable('guid');\n\n// You can enable transforms with `.enable`\nBucky.requests.tranforms.enable('guid');\n\n// `.enable` can also be used to add a new tranform:\nBucky.requests.transforms.enable('my-ids', /[0-9]{4}-[0-9]{12}/g)\n\n// The third argument defines what the match is replaced with (rather than just eliminating it):\nBucky.requests.transforms.enable('campaign', /campaigns\\/\\w{15}/ig, '/campaigns')\n\n// You can also just provide a function which takes in the url, and returns it modified:\nBucky.request.transforms.enable('soup', function(url){ return url.split('').reverse().join(''); })\n```\n\nEnabled tests will be added to the beginning of the `enabled` list, meaning they will be executed before\nany other tranform.  Edit the `Bucky.requests.tranforms.enabled` array if you need more specific control.\n\nThe order of the transforms is very important.  If you, for example, were to run the `id` transform before\nthe `guid` one, the `guid` transform wouldn't match any guid which began with a number (as the number would\nhave already been stripped out, making the guid the wrong length).\n\nWhen you first enable request monitoring, it's a good idea to keep an eye on the Bucky logs to get\nan idea of what sort of data points are being created.\n\n### App Server\n\nThis project pushes data to the Bucky Server.\n\n[Server Documentation](http://github.hubspot.com/BuckyServer)\n\n\u003cscript src=\"http://github.hubspot.com/BuckyClient/bucky.js\"\u003e\u003c/script\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHubSpot%2FBuckyClient","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FHubSpot%2FBuckyClient","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHubSpot%2FBuckyClient/lists"}