{"id":27594446,"url":"https://github.com/apache/couchdb-folsom","last_synced_at":"2025-04-22T10:34:35.245Z","repository":{"id":14091967,"uuid":"16795933","full_name":"apache/couchdb-folsom","owner":"apache","description":"Mirror of Apache CouchDB","archived":false,"fork":false,"pushed_at":"2023-07-18T12:37:25.000Z","size":638,"stargazers_count":5,"open_issues_count":1,"forks_count":8,"subscribers_count":18,"default_branch":"main","last_synced_at":"2025-04-18T04:04:51.459Z","etag":null,"topics":["big-data","cloud","content","couchdb","cplusplus","database","erlang","http","javascript","network-client","network-server"],"latest_commit_sha":null,"homepage":null,"language":"Erlang","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apache.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,"zenodo":null}},"created_at":"2014-02-13T08:00:09.000Z","updated_at":"2023-07-25T13:50:50.000Z","dependencies_parsed_at":"2025-04-17T14:54:18.633Z","dependency_job_id":"c3c76598-2f2e-4ccf-9946-8b69d5a12758","html_url":"https://github.com/apache/couchdb-folsom","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fcouchdb-folsom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fcouchdb-folsom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fcouchdb-folsom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fcouchdb-folsom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apache","download_url":"https://codeload.github.com/apache/couchdb-folsom/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250153636,"owners_count":21383640,"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":["big-data","cloud","content","couchdb","cplusplus","database","erlang","http","javascript","network-client","network-server"],"created_at":"2025-04-22T10:32:34.849Z","updated_at":"2025-04-22T10:34:35.228Z","avatar_url":"https://github.com/apache.png","language":"Erlang","funding_links":[],"categories":[],"sub_categories":[],"readme":"### folsom\n\nFolsom is an Erlang based metrics system inspired by Coda Hale's metrics (https://github.com/codahale/metrics/). The metrics API's purpose is to collect realtime metrics from your Erlang applications and publish them via Erlang APIs and output plugins. folsom is *not* a persistent store. There are 6 types of metrics: counters, gauges, histograms (and timers), histories, meter_readers and meters. Metrics can be created, read and updated via the `folsom_metrics` module.\n\n#### Building and running\n\nFirst, regarding using folsom and folsom_webmachine together. To make sure you have compatible versions of each, make sure you use code from the same version tags, ie 0.5 of folsom is known to work with 0.5 folsom_webmachine. HEAD on each repo may have broken API compatibility.\n\nYou need a (preferably recent) version of Erlang installed but that should be it.\n\n       ./rebar get-deps compile\n\nfolsom can be run standalone or embedded in an Erlang application.\n\n       $ erl -pa ebin deps/*/ebin\n\n       \u003e folsom:start(). % this creates the needed ETS tables and starts a gen_server\n\nYou can also start it as an application:\n\n       $ erl -pa ebin deps/*/ebin\n       \u003e application:start(folsom).\n\n       $ erl -pa ebin deps/*/ebin -s folsom\n\nThe application can be configured to create individual or lists of metrics at\nstartup on the command line or in an application config file:\n\n       $ erl -pa ebin deps/*/ebin -s folsom \\\n          -folsom history '[hist1,hist2]' \\\n          -folsom gauge gauge1\n\n       $ echo '[{folsom, [{history, [hist1, hist2]}, {gauge, gauge1}]}].' \\\n          \u003e myapp.config\n       $ erl -pa ebin deps/*/ebin -config myapp.config -s folsom\n\n#### Metrics API\n\nfolsom_metrics.erl is the API module you will need to use most of the time.\n\nRetrieve a list of current installed metrics:\n\n      \u003e folsom_metrics:get_metrics().\n\nQuery a specific metric:\n\n      \u003e folsom_metrics:get_metric_value(Name).\n\nGenerally names of metrics are atoms or binaries.\n\n##### Counters\n\nCounter metrics provide increment and decrement capabilities for a single scalar value.\n\n      \u003e folsom_metrics:new_counter(Name).\n      \u003e folsom_metrics:notify({Name, {inc, Value}}).\n      \u003e folsom_metrics:notify({Name, {dec, Value}}).\n\n##### Gauges\n\nGauges are point-in-time single value metrics.\n\n      \u003e folsom_metrics:new_gauge(Name).\n      \u003e folsom_metrics:notify({Name, Value}).\n\n##### Histograms (and Timers)\n\nHistograms are collections of values that have statistical analysis done to them, such as mean, min, max, kurtosis and percentile. They can be used like \"timers\" as well with the timed update functions.\n\n      \u003e folsom_metrics:new_histogram(Name).\n      \u003e folsom_metrics:histogram_timed_update(Name, Mod, Fun, Args).\n      \u003e folsom_metrics:histogram_timed_update(Name, Fun, Args).\n      \u003e folsom_metrics:histogram_timed_update(Name, Fun).\n      \u003e folsom_metrics:notify({Name, Value}).\n\n###### Histogram sample types\n\nEach histogram draws its values from a `reservoir` of readings. You can select a `sample type` for a histogram by passing the name of the sample type as an atom when you create a new histogram.\nSome sample types have further arguments. The purpose of a sample type is to control the size and charecteristics of the reservoir of readings the histogram performs analysis upon.\n\nFolsom currently provides the following sample types:\n\n######  `uniform`\n\nThis is a random uniform sample over the stream of readings. This is the default sample type, bounded in size to 1028 readings. When `size` readings have been taken, new readings replace older readings\nin the reservoir at random. You can set the sample size at creation time:\n\n      \u003e folsom_metrics:new_histogram(Name, uniform, Size::integer()).\n\nBe sure you understand _why_ before you do this.\n\n###### `exdec`\n\nThis is a  sample that exponentially decays less significant readings over time so as to give greater significance to newer readings. Read more here -\n[Forward Decay...](http://www.research.att.com/people/Cormode_Graham/library/publications/CormodeShkapenyukSrivastavaXu09.pdf).\nAgain you can change defaults at creation time, if you think you need to:\n\n    \u003e folsom_metrics:new_histogram(Name, exdec, Size::integer(), Alpha::float()).\n\n###### `slide`\n\nThis is a sliding window in time over a stream of readings. The default window size is 60 seconds. Every reading that occurs in a sliding sixty second window is stored,\nwith older readings being discarded. If you have a lot of readings per\nminute the `reservoir` may get pretty big and so it will take more time to calculate statistics. You can set the `window` size by providing a number of seconds.\n\n    \u003e folsom_metrics:new_histogram(Name, slide, Seconds::integer()).\n\n###### `slide_uniform`\n\nThis is a sliding window in time over a stream of readings with a random uniform sample per second, to bound the size of the total number of readings. The maximum size of the reservoir will be\n `window size * sample size`. Default is a window of 60 seconds and a sample size of 1028. Again, you can change these at creation time:\n\n    \u003e folsom_metrics:new_histogram(Name, slide_uniform, {Secs::interger(), Size::integer()).\n\n##### Histories\n\nHistories are a collection of past events, such as errors or log messages.\n\n      \u003e folsom_metrics:new_history(Name).\n      \u003e folsom_metrics:get_history_values(Name, Count). % get more than the default number of history items back\n      \u003e folsom_metrics:notify({Name, Value}).\n\n##### Meters\n\nMeters are increment only counters with mean rates and exponentially weighted moving averages applied to them, similar to a unix load average.\n\n      \u003e folsom_metrics:new_meter(Name).\n      \u003e folsom_metrics:notify({Name, Value}).\n\n###### `Spiral` meter\n\nA `spiral` is a type of meter that has a one minute sliding window count. The meter tracks an increment only counter and a total for the last minute. This is a sliding count with older readings dropping off per second.\n\n    \u003e folsom_metrics:new_spiral(Name).\n    \u003e folsom_metrics:notify({Name, Count}).\n\n##### Meter Reader\n\nMeter readers are like a meter except that the values passed to it are monotonically increasing, e.g., reading from a water or gas meter, CPU jiffies, or I/O operation count.\n\n      \u003e folsom_metrics:new_meter_reader(Name).\n      \u003e folsom_metrics:notify({Name, Value}).\n\n##### Metrics groups/tags\n\nCertain users might want to group and query metrics monitoring a common task. In order to do so, they can\ntag metrics:\n\n    \u003e folsom_metrics:tag_metric(Name, Tag).\n\nand untag metrics:\n\n    \u003e folsom_metrics:untag_metric(Name, Tag).\n\nUsers can query a list of tuples `[{Name, Value}]` of all metrics with a given tag:\n\n    \u003e folsom_metrics:get_metrics_value(Tag).\n\nIf only a certain type of metrics from a given group is desired, one can specify so:\n\n    \u003e folsom_metrics:get_metrics_value(Tag, Type).\n\nwhere Type is one of `counter`, `gauge`, `histogram`, `history`, `meter`, `meter_reader`, `duration` or `spiral`.\n\n##### Erlang VM\n\nfolsom also produces Erlang VM statistics.\n\nThe result of `erlang:memory/0`:\n\n       \u003e folsom_vm_metrics:get_memory().\n\nThe result of `erlang:system_info/1`:\n\n       \u003e folsom_vm_metrics:get_system_info().\n\nThe result of `erlang:statistics/1`:\n\n       \u003e folsom_vm_metrics:get_statistics().\n\nThe result of `erlang:process_info/1`:\n\n       \u003e folsom_vm_metrics:get_process_info(). %% use with caution\n\nThe result of `inet:getstat/1`, `prim_inet:getstatus/1`, `erlang:port_info/1`, `prim_inet:gettype/1`, `inet:getopts/1`, `inet:sockname/1`:\n\n       \u003e folsom_vm_metrics:get_port_info(). %% use with caution\n\nThe result from `ets:info/1` and `dets:info/1` across all tables\n\n       \u003e folsom_vm_metrics:get_ets_info().\n       \u003e folsom_vm_metrics:get_dets_info().\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapache%2Fcouchdb-folsom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapache%2Fcouchdb-folsom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapache%2Fcouchdb-folsom/lists"}