{"id":15647839,"url":"https://github.com/ncarlier/apimon","last_synced_at":"2025-04-30T13:23:54.459Z","repository":{"id":57532108,"uuid":"120127442","full_name":"ncarlier/apimon","owner":"ncarlier","description":"APImon is a simple tool for monitoring HTTP endpoints and sending metrics to a robust monitoring platform (such as TICK, Prometheus, ELK, etc.).","archived":false,"fork":false,"pushed_at":"2021-06-18T09:08:12.000Z","size":552,"stargazers_count":43,"open_issues_count":0,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-30T13:22:38.794Z","etag":null,"topics":["api-monitor","elasticsearch","health-check","influxdb","metrics","monitoring","monitoring-tool","prometheus"],"latest_commit_sha":null,"homepage":"","language":"Go","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/ncarlier.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-02-03T20:35:38.000Z","updated_at":"2024-11-15T05:50:46.000Z","dependencies_parsed_at":"2022-09-05T09:50:32.355Z","dependency_job_id":null,"html_url":"https://github.com/ncarlier/apimon","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncarlier%2Fapimon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncarlier%2Fapimon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncarlier%2Fapimon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncarlier%2Fapimon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ncarlier","download_url":"https://codeload.github.com/ncarlier/apimon/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251711966,"owners_count":21631309,"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":["api-monitor","elasticsearch","health-check","influxdb","metrics","monitoring","monitoring-tool","prometheus"],"created_at":"2024-10-03T12:21:30.413Z","updated_at":"2025-04-30T13:23:54.404Z","avatar_url":"https://github.com/ncarlier.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# apimon\n\n[![Build Status](https://github.com/ncarlier/apimon/actions/workflows/build.yml/badge.svg)](https://github.com/ncarlier/apimon/actions/workflows/build.yml)\n[![Image size](https://images.microbadger.com/badges/image/ncarlier/apimon.svg)](https://microbadger.com/images/ncarlier/apimon)\n[![Docker pulls](https://img.shields.io/docker/pulls/ncarlier/apimon.svg)](https://hub.docker.com/r/ncarlier/apimon/)\n\nAPImon is a simple tool to monitor HTTP endpoints and send metrics to a\nrobust monitoring platform (such as TICK, Prometheus, ELK, etc.).\n\n![Logo](apimon.svg)\n\n## Installation\n\nRun the following command:\n\n```bash\n$ go get -v github.com/ncarlier/apimon\n```\n\n**Or** download the binary regarding your architecture:\n\n```bash\n$ sudo curl -s https://raw.githubusercontent.com/ncarlier/apimon/master/install.sh | bash\n```\n\n**Or** use Docker:\n\n```bash\n$ docker run -d --name=apimon \\\n  -v ${PWD}/apimon.yml:/etc/apimon.yml \\\n  ncarlier/apimon apimon -c /etc/apimon.yml\n```\n\nHere a [Docker Compose example](./docker-compose.yml).\n\n## Configuration\n\nThe configuration is a YAML file structured like this:\n\n```yaml\noutput:              # Output configuration\n  traget: stdout     # Output target (default: stdout)\n  format: influxdb   # Output format (default: influxdb)\nproxy: ${HTTP_PROXY} # Global HTTP proxy to use (default: none)\nuser_agent: \"Mozilla/5.0 (X11; Linux x86_64; rv:10.0) Gecko/20100101 Firefox/10.0\" # UserAgent used (default: Mozilla/5.0 (compatible; APImon/1.0; +https://github.com/ncarlier/apimon))\nhealthcheck:         # Global healthcheck configuration\n  interval: 5s       # Check interval (default: 30s)\n  timeout: 2s        # Request timeout (default: 5s)\n  rules:             # List of rules (default: \"code = 200\")\n    - name: code\n      spec: 200-299\nmonitors_files: # List of external monitors configuration (default: none)\n  - \"monitor_*.yml\" # File to load (support wildcard)\nmonitors: # List of monitors configuration\n  - alias: nunux-keeper-api # The name used within the produced metrics (default: the URL)\n    disable: false # Disable the monitor (default: false)\n    url: https://api.nunux.org/keeper/ # The URL to monitor\n    method: GET # HTTP method used (default: GET)\n    headers: # HTTP headers to add to the request (default: none)\n      - \"X-API-Key: xxx-xxx-xxx\"\n    body: \u003e # HTTP request body\n      { \"foo\": \"bar\" }\n    proxy: http://proxy-internet.localnet:3128 # Specific HTTP proxy to use. Replaces the global configuration (default: none)\n    tls:\n      unsafe: true # Don't verifies the server's certificate chain and host name (default: false)\n      client_cert_file: ./cert.pem # PEM encoded client certificate file (default: none)\n      client_key_file: ./key.pem   # PEM encoded client key file (default: none\n      ca_cert_file: ./key.pem      # PEM encoded CA's certificate file (default: none)\n    healthcheck: # Monitor specific configuration. Replaces the global configuration.\n      timeout: 100ms\n      rules:\n        - name: code\n          spec: 200\n  - url: https://reader.nunux.org\n```\n\nNote: As the proxy example shows, you can use environment variables in your configuration file.\n\n### Output configuration\n\nThis configuration section allows you to set the targeted output\n(i. e. your monitoring platform).\n\n- `stdout`: Prints metrics to the STDOUT.\n- `file://test.log`: Writes metrics to a log file.\n- `http://...`:\n  - Post metrics to an HTTP endpoint such as [InfluxDb][influxdb],\n  [Elasticsearch][elasticsearch], etc. (Push Mode)\n  - OR serve metrics on this HTTP endpoint if `prometheus` format is used (Pull mode)\n\n\u003e Note: When you are using `stdout` you should use the logging output flag\n\u003e (`-o`) in order to not mix metrics and logs outputs.\n\nYou can also choose the output format:\n\n- `influxdb`: [InfluxDb line protocol][influxdb-line-protocol] (when using a\n  collector compatible with [InfluxDB][influxdb])\n- `json`: JSON format (when using [Elasticsearch][elasticsearch] like solution)\n- `prometheus`: when using [Prometheus][prometheus] as collector\n\n\u003e Note: When using `prometheus` format the output configuration must be a local\n\u003e HTTP endpoint.\n\u003e This endpoint will be mounted by APImon and you will be able to\n\u003e [configure](./prometheus.yml) Prometheus to scrap this target.\n\n### Healthcheck configuration\n\nYou can configure the health check in a global way (for all monitors) by placing\nthis section at the root level of the configuration file.\nIf you configure the health check of a specific monitor, the configuration\napplies upon the global one.\n\nA health check is defined like this:\n\n- `interval`: the waiting time between checks\n- `timeout`: the maximum time allowed for a check\n- `rules`: the list of validation rules\n\nA rule have the following structure:\n\n- `name`: rule name\n- `spec`: rule specification\n\nThe `name` selects the validator to be applied.\nAnd `spec` is the configuration of the validator.\n\nValidators are chained (using list order).\nThe first failed validator stops the validation chain and the monitor is\nconsidered as DOWN.\n\n### Available validators\n\nName   | Spec \n-------|------\n`code` | Validates status code (ex: `200`)\u003cbr\u003eValidates status code in a list (ex: `200,204,205`)\u003cbr\u003eValidates status code within an interval (ex: `200-204`)\n`json-path` | Validates JSON response with a [JSON path][jsonpath-syntax] expression (ex: `$.service[?(@.status == 'UP')]`)\n`json-expr` | Validates JSON response with an [expression][expr-syntax] (ex: `service.status == \"UP\" \u0026\u0026 uptime \u003c 100)]`)\n`regexp` | Validates body response with a [regular expression][regexp-syntax] (ex: `^ok$`)\n`cert` | Validates certificate expiration date is before N days (ex: `30`)\n\n### Service Discovery and dynamic configuration\n\nAPImon can work alongside [Consul](https://www.consul.io/).\nTo do so you must configure the [Consul environment variables](https://www.consul.io/docs/commands/index.html#environment-variables).\n\nEx:\n\n```bash\n$ # Configure Consul access\n$ export CONSUL_HTTP_ADDR=127.0.0.1:8500\n$ # Start APImon\n$ apimon\n```\nAPImon will then register as a service and you can use the K/V store for monitors configuration.\n\nThe configuration is stored in the `apimon/monitors' key in YAML:\n\n```yaml\n- alias: google\n  url: https://www.google.com\n```\n\nThis is the equivalent of the `monitors' section of the configuration file.\n\nUpdating this key will reload APImon monitors.\n\n## Usage\n\nType `apimon -help` to get the usage.\n\nBasically, all you have to do is to provide the configuration file either using\nthe `-c` parameter or the standard input of the command.\n\nHere come examples of possible usages:\n\n```bash\n$ # Using the default configuration file: `./apimon.yml`\n$ apimon\n$ # Using a specific configuration file\n$ apimon -c /etc/apimon.yml\n$ # Using a configuration file provided by the shell standard input\n$ cat conf.yml | apimon\n$ ...\n```\n\nHere an example of a Grafana dashboard displaying metrics form APImon:\n\n![screenshot](screenshot.png)\n\nYou can find dashboard examples into the `dashboard` folder:\n\n- [Grafana dashboard using InfluxDB](./dashboard/influxdb_sample.json)\n- [Grafana dashboard using Prometheus](./dashboard/prometheus_sample.json)\n\n## FAQ\n\n### I am using InfluxDB with UDP\n\nThis is why `stdout` output is designed.\nYou can pipe the standard output to `netcat`:\n\n```bash\n$ # Sending metrics to InfluxDb using UDP\n$ cat conf.yml | apimon -o output.log | nc -C -w 1 -u localhost 8125\n```\n\n### I am using Elasticsearch\n\nYou can either send the metrics (using JSON format as output configuration!)\ndirectly to Elasticsearch:\n\n```bash\n$ apimon -c config.yml -o output.log | curl -X POST - -d @- http://localhost:9200/index/doc\n$ # You can also directly use the HTTP output provider into the APIMon configuration\n```\n\nor better: use [Logstash][logstash] to collect the JSON outputs:\n\n```\ninput {\n  pipe {\n    type =\u003e \"apimon\"\n    debug =\u003e true\n    command =\u003e \"/usr/local/apimon -c /etc/apimon.yml -o /var/log/apimon.log\"\n  }\n}\n```\n---\n\nThis software is under MIT License (MIT)\n\nCopyright (c) 2018 Nicolas Carlier\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\n[elasticsearch]: https://www.elastic.co/products/elasticsearch\n[logstash]: https://www.elastic.co/products/logstash\n[influxdb]: https://github.com/influxdata/influxdb\n[influxdb-line-protocol]: https://docs.influxdata.com/influxdb/v1.4/write_protocols/line_protocol_tutorial/\n[prometheus]: https://prometheus.io/\n[regexp-syntax]: https://golang.org/pkg/regexp/syntax/\n[expr-syntax]: https://github.com/antonmedv/expr/wiki/The-Expression-Syntax\n[jsonpath-syntax]: http://goessner.net/articles/JsonPath/index.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fncarlier%2Fapimon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fncarlier%2Fapimon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fncarlier%2Fapimon/lists"}