{"id":15285834,"url":"https://github.com/katja-beam/katja","last_synced_at":"2025-08-09T07:06:23.590Z","repository":{"id":16430886,"uuid":"19182286","full_name":"katja-beam/katja","owner":"katja-beam","description":"A simple Riemann client written in Erlang.","archived":false,"fork":false,"pushed_at":"2020-05-24T14:04:50.000Z","size":348,"stargazers_count":27,"open_issues_count":4,"forks_count":19,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-26T20:06:11.842Z","etag":null,"topics":["erlang","query-riemann","riemann","riemann-client"],"latest_commit_sha":null,"homepage":"https://hex.pm/packages/katja","language":"Erlang","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/katja-beam.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2014-04-26T16:32:56.000Z","updated_at":"2024-05-04T22:12:23.000Z","dependencies_parsed_at":"2022-09-17T00:32:19.293Z","dependency_job_id":null,"html_url":"https://github.com/katja-beam/katja","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katja-beam%2Fkatja","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katja-beam%2Fkatja/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katja-beam%2Fkatja/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katja-beam%2Fkatja/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/katja-beam","download_url":"https://codeload.github.com/katja-beam/katja/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248543884,"owners_count":21121838,"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":["erlang","query-riemann","riemann","riemann-client"],"created_at":"2024-09-30T15:07:48.227Z","updated_at":"2025-04-13T02:41:42.954Z","avatar_url":"https://github.com/katja-beam.png","language":"Erlang","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Katja\n\nA simple [Riemann](http://riemann.io) client written in Erlang.\n\n[![Build Status](https://travis-ci.org/katja-beam/katja.png)](https://travis-ci.org/katja-beam/katja) [![Coverage Status](https://coveralls.io/repos/github/katja-beam/katja/badge.svg?branch=master)](https://coveralls.io/github/katja-beam/katja?branch=master)\n\n## Status\n\nThis is alpha software. Things might still change in ways that break everything.\n\n## Configuration\n\n```erlang\n% Defaults\n[\n  {katja, [\n    {host, \"127.0.0.1\"},\n    {port, 5555},\n    {transport, detect},\n    {pool, []},\n    {defaults, []}\n  ]}\n].\n```\n\n**host**: Host Riemann is running on\n\n**port**: Port Riemann is listening on\n\n**transport**: The message transport that should be used (supported: `detect`, `udp`, `tcp`)\n\n**pool**: List of processes that should not be started (and supervised) by Katja (supported: `katja_reader`, `katja_writer`)\n\n**defaults**: Property list with default values for events and states (supported: `host`, `tags`, `ttl`)\n\n## Examples\n\n### Sending an event\n\n```erlang\nEvent = [{service, \"katja demo\"}, {metric, 9000.1}],\nok = katja:send_event(Event).\n```\n\nAn event in Katja is just a property list. A list of all possible properties can be found in the `katja` module.\n\nYou can send an event asynchronously using `katja:send_event_async/{1,2,3}`:\n\n```erlang\nEvent = [{service, \"katja demo\"}, {metric, 9000.1}],\nok = katja:send_event_async(Event).\n```\n\nThis will return immediately and you will **not** know if the call has succeeded.\n\n### Sending a state\n\n```erlang\nState = [{service, \"katja demo\"}, {state, \"testing\"}],\nok = katja:send_state(State).\n```\n\nJust like events, a state is a property list. The properties can once again be found in the `katja` module.\n\nJust like for events, you can use `katja:send_state_async/{1,2,3}` to send states in a non-blocking way.\n\n### Sending multiple entities\n\n```erlang\nEvent = [{service, \"katja demo\"}, {metric, 9000.1}],\nState = [{service, \"katja demo\"}, {state, \"testing\"}],\nok = katja:send_entities([{events, [Event, Event]}, {states, [State, State]}]).\n```\n\n`katja:send_entities/1` takes a property list with two possible properties: `events` should be set to a list of events and `states` should be set to a list of states.\n\nBoth properties are optional, so `katja:send_entities/1` can be used to only send multiple events or states.\n\n```erlang\nEvent = [{service, \"katja demo\"}, {metric, 9000.1}],\nState = [{service, \"katja demo\"}, {state, \"testing\"}],\nok = katja:send_events([Event]),\nok = katja:send_states([State]).\n```\n\n`katja:send_events/1` and `katja:send_states/1` are also available to send multiple events or states. Both of them delegate to `katja:send_entities/1` internally.\n\nSending entities asynchronously is also possible. All of the methods mentioned above have matching `_async/{1,2,3}` counterparts.\n\n### Querying\n\n```erlang\n{ok, Events} = katja:query(\"service = \\\"katja demo\\\"\").\n```\n\nA query returns a list of events. Events are in the format that you specify when sending data to Riemann.\n\nInstead of a string you can also use a `katja:event()` and the `katja:query_event/1` method to send queries to Riemann.\n\n```erlang\n{ok, Events} = katja:query_event([{service, \"katja demo\"}]).\n```\n\nKatja will convert the event to a query string and query Riemann based on the generated string.\n\nYou can use `katja:query_async/{1,2}` and `katja:query_event_async/{1,2}` to send queries asynchronously. The results will be sent to the inbox of the calling process.\n\n```erlang\nRef = katja:query_async(\"service = \\\"katja demo\\\"\"),\nreceive\n  {Ref, {ok, Events}} -\u003e\n    % ...\nend.\n```\n\n### Pooling\n\nAll the methods mentioned above optionally take a `katja:process()` as their first argument, enabling Katja to easily work with existing process pool implementations. `katja:process()` is either a `pid()` or one of the two following atoms: `katja_writer`, `katja_reader`.\n\nThe `atom()` cases usually don't have to be used directly, since `katja:send_event/1`, `katja:send_state/1`, `katja:query/1` etc. default to setting the correct value.\n\nAdditionally you can also \"turn off\" the `katja_writer` and `katja_reader` processes that are automatically started and supervised by adding their names to the `pool` configuration option.\n\n### Forcing a transport\n\nYou can force a message to be send via TCP or UDP. By default, the transport is chosen based on the size of a message: UDP is used for messages up to 16Kb in size, everything larger than that uses TCP. Querying Riemann always uses TCP.\n\n```erlang\nEvent = [{service, \"katja demo\"}, {metric, 9000.1}],\nok = katja:send_event(katja_writer, tcp, Event).\n```\n\nThe first argument to `katja:send_event/3`, `katja:send_events/3`, `katja:send_state/3`, `katja:send_states/3` and `katja:send_entities/3` is a `katja:process()`. If you're using one of these methods and don't use a process pool, it has to be set to `katja_writer`.\n\nYou can set the `transport` configuration option to `tcp` or `udp` to always use that transport for sending data to Riemann.\n\n## Resources\n\n* [Generated EDoc](https://hexdocs.pm/katja)\n* [Katja: Riemann Client Written In Erlang](https://blog.kempkens.io/posts/katja-riemann-client-written-in-erlang/)\n\n## Related Projects\n\n* [Katja VM Stats](https://github.com/katja-beam/katja_vmstats) - Easily send information about the Erlang VM to Riemann\n\n## License\n\n[ISC](https://en.wikipedia.org/wiki/ISC_license).\n\n```\nCopyright (c) 2014-2016, Daniel Kempkens \u003cdaniel@kempkens.io\u003e\nCopyright The katja-beam Contributors\n\nPermission to use, copy, modify, and/or distribute this software for any purpose\nwith or without fee is hereby granted, provided that the above copyright notice\nand this permission notice appear in all copies.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH\nREGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND\nFITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,\nINDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS\nOF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER\nTORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF\nTHIS SOFTWARE.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkatja-beam%2Fkatja","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkatja-beam%2Fkatja","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkatja-beam%2Fkatja/lists"}