{"id":15056878,"url":"https://github.com/smartcat-labs/cassandra-diagnostics","last_synced_at":"2025-04-10T04:55:48.945Z","repository":{"id":57736223,"uuid":"56258575","full_name":"smartcat-labs/cassandra-diagnostics","owner":"smartcat-labs","description":"Cassandra Node Diagnostics Tools","archived":false,"fork":false,"pushed_at":"2017-09-18T11:55:47.000Z","size":1233,"stargazers_count":51,"open_issues_count":24,"forks_count":6,"subscribers_count":24,"default_branch":"dev","last_synced_at":"2025-03-24T06:11:27.828Z","etag":null,"topics":["cassandra","diagnostics","monitoring","tool"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"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/smartcat-labs.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":"2016-04-14T17:53:45.000Z","updated_at":"2021-04-14T02:31:47.000Z","dependencies_parsed_at":"2022-08-23T22:40:52.664Z","dependency_job_id":null,"html_url":"https://github.com/smartcat-labs/cassandra-diagnostics","commit_stats":null,"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcat-labs%2Fcassandra-diagnostics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcat-labs%2Fcassandra-diagnostics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcat-labs%2Fcassandra-diagnostics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcat-labs%2Fcassandra-diagnostics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smartcat-labs","download_url":"https://codeload.github.com/smartcat-labs/cassandra-diagnostics/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248161257,"owners_count":21057554,"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":["cassandra","diagnostics","monitoring","tool"],"created_at":"2024-09-24T21:57:29.440Z","updated_at":"2025-04-10T04:55:48.925Z","avatar_url":"https://github.com/smartcat-labs.png","language":"Java","funding_links":[],"categories":["General"],"sub_categories":["Cassandra Performance Tuning"],"readme":"# Cassandra Diagnostics\n\nMonitoring and audit power kit for Apache Cassandra.\n\n[![Build Status](https://travis-ci.org/smartcat-labs/cassandra-diagnostics.svg?branch=master)](https://travis-ci.org/smartcat-labs/cassandra-diagnostics)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.smartcat/cassandra-diagnostics/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.smartcat/cassandra-diagnostics/)\n[![Download](https://api.bintray.com/packages/smartcat-labs/maven/cassandra-diagnostics/images/download.svg) ](https://bintray.com/smartcat-labs/maven/cassandra-diagnostics/_latestVersion)\n\n## Introduction\n\nCassandra Diagnostics is an extension for Apache Cassandra server node implemented as Java agent. It uses bytecode instrumentation to augment Cassandra node with additional functionalities. The following images depicts the position of Cassandra Diagnostics in a Apache Cassandra based system.\n\n![Placement diagram](diagrams/cassandra-diagnostics.png?raw=true)\n\nCassandra Diagnostics has a modular architecture. On one side it has connectors for different versions of Apache Cassandra nodes or Cassandra Java Driver and on the other it has various reporters to send measurement to different collecting/monitoring tools. In between lies the core with a set of metrics processing modules. Reusable code goes to commons.\n\n![Architecture diagram](diagrams/architecture-diagram.png?raw=true)\n\n### Cassandra Diagnostic Commons\n\n[Cassandra Diagnostics Commons](cassandra-diagnostics-commons/) holds interface for core, connector and reports and it provides signature all the modules need to confront to be able to work together.\n\n### Cassandra Connector\n\nConnector is a module which hooks into the query path and extract information for diagnostics. Bytecode instrumentation is used to augment existing Cassandra code with additional functionality. It uses low priority threads to execute the diagnostics information extraction with minimal performance impact to the target code (Cassandra node or application/driver).\n\nCurrently Cassandra Diagnostics implements the following connector implementation:\n\n- [Cassandra Connector 2.1](cassandra-diagnostics-connector21/) is a connector implementation for Cassandra node for Cassandra version 2.1.x.\n\n- [Cassandra Connector 3.0](cassandra-diagnostics-connector30/) is a connector implementation for Cassandra node for Cassandra version 3.0.x.\n\n- [Cassandra Driver Connector](cassandra-diagnostics-driver-connector/) is a connector implementation for Datastax's Cassandra driver for diagnostics on the application side.\n\n### Cassandra Core\n\n[Cassandra Diagnostics Core](cassandra-diagnostics-core/) is glue between connector and reporters. It holds all the modules for diagnostics, it has business logic for measurement and it decides what will be measured and what would be skipped. Its job is to load provided configuration or to setup sensible defaults.\n\n### Modules\n\nThere are default module implementations which serve as core features. Modules use configured reporters to report their activity.\n\nPlease read [core modules README](cassandra-diagnostics-core/COREMODULES.md) for more information and configuraion options for the modules.Core module implementations:\n\n#### Heartbeat Module\n\n[Heartbeat Module](cassandra-diagnostics-core/COREMODULES.md#heartbeat-module) produces messages to provide feedback that the diagnostics agent is loaded and working. Typical usage is with Log Reporter where it produces INFO message in configured intervals.\nDefault reporting interval is 15 minutes.\n\n#### Slow Query Module\n\n[Slow Query Module](cassandra-diagnostics-core/COREMODULES.md#slow-query-module) is monitoring execution time of each query and if it is above configured threshold it reports the value and query type using configured reporters.\nDefault query execution time threshold is 25 milliseconds.\n\n#### Request Rate Module\n\n[Request Rate Module](cassandra-diagnostics-core/COREMODULES.md#request-rate-module) uses codahale metrics library to create rate measurement of executed queries. Rates are reported for configurable statement types and consistency levels using configured reporters in configured periods.\nDefault reporting interval is 1 second.\n\n#### Metrics Module\n\n[Metrics Module](cassandra-diagnostics-core/COREMODULES.md#metrics-module) collects Cassandra's metrics, which are exposed over JMX, and ships them using predefined reporters. Metrics package names configuration is the same as a default metrics config reporter uses.\nDefault reporting interval is 1 second.\n\n#### Status Module\n\n[Status Module](cassandra-diagnostics-core/COREMODULES.md#status-module) is used to report Cassandra information exposed over JMX. It reports compaction information as a single measurement.\nDefault reporting interval is 1 minute.\n\n#### Cluster Health Module\n\n[Cluster Health Module](cassandra-diagnostics-core/COREMODULES.md#cluster-health-module) is used to report the health status of the nodes such as which nodes are marked as DOWN by gossiper. It uses the information exposed over JMX.\nDefault reporting interval is 10 seconds.\n\n#### Hiccup Module\n\nModule based on [jHiccup](https://github.com/giltene/jHiccup) that logs and reports platform hiccups including JVM stalls. Default reporting period is 5 seconds and reporter values and percentiles from 90 to 100 and Mean and Max values.\n\n### Reporters\n\nReporters take measurement from core and wrap them up in implementation specific format so it can be sent to reporters target (i.e. Influx reporter transforms measurement to influx query and stores it to InfluxDB).\n\nReporter implementations:\n\n#### Log Reporter\n\n[LogReporter](cassandra-diagnostics-core/src/main/java/io/smartcat/cassandra/diagnostics/reporter/LogReporter.java) uses the Cassandra logger system to report measurement (this is default reporter and part of core). Reports are logged at the `INFO` log level in the following pattern:\n\n```\nMeasurement {} [time={}, value={}, tags={}, fields={}]\n```\n\nValues for `time` is given in milliseconds. `tags` are used to better specify measurement and provide additional searchable labels and fields is a placeholder for additional fields connected to this measurement. Example can be Slow Query measurement, where `value` is execution time of query, `tags` can be type of statement (UPDATE or SELECT) so you can differentiate and search easy and `fields` can hold actual statement, which is not something you want to search against but it is valuable metadata for measurement.\n\n#### Riemann Reporter\n\n[RiemannReporter](cassandra-diagnostics-reporter-riemann/README.md) sends measurements towards [Riemann server](http://riemann.io/).\n\n#### Influx Reporter\n\n[InfluxReporter](cassandra-diagnostics-reporter-influx/README.md) sends measurements towards [Influx database](https://www.influxdata.com/time-series-platform/influxdb/).\n\n#### Telegraf Reporter\n\n[Telegraf Reporter](cassandra-diagnostics-reporter-telegraf/README.md) sends measurements towards [Telegraf agent](https://github.com/influxdata/telegraf).\n\n#### Datadog Reporter\n\n[Datadog Reporter](cassandra-diagnostics-reporter-datadog/README.md) sends measurements towards [Datadog Agent](https://github.com/DataDog/dd-agent) using UDP.\n\n#### Kafka Reporter\n\n[Kafka Reporter](cassandra-diagnostics-reporter-kafka/README.md) sends measurements towards [Kafka](https://kafka.apache.org/).\n\n#### Prometheus Reporter\n\n[Prometheus Reporter](cassandra-diagnostics-reporter-prometheus/README.md) exposes measurements to be scraped by [Prometheus server](https://prometheus.io).\n\n## Configuration\n\nCassandra Diagnostics uses an external configuration file in YAML format. You can see default configuration in [cassandra-diagnostics-default.yml](https://github.com/smartcat-labs/cassandra-diagnostics/blob/dev/cassandra-diagnostics-core/src/main/resources/cassandra-diagnostics-default.yml). The default name of the config file is `cassandra-diagnostics.yml` and it is expected to be found on the classpath. This can be changed using property `cassandra.diagnostics.config`.\nFor example, the configuration can be set explicitly by changing `cassandra-env.sh` and adding the following line:\n\n```\nJVM_OPTS=\"$JVM_OPTS -Dcassandra.diagnostics.config=some-other-cassandra-diagnostics-configuration.yml\"\n```\n\nThe following is an example of the configuration file:\n\n```\nglobal:\n  systemName: \"smartcat-cassandra-cluster\"\n\nreporters:\n  - reporter: io.smartcat.cassandra.diagnostics.reporter.LogReporter\n\nmodules:\n  - module: io.smartcat.cassandra.diagnostics.module.slowquery.SlowQueryModule\n    measurement: queryReport\n    options:\n      slowQueryThresholdInMilliseconds: 1\n    reporters:\n      - io.smartcat.cassandra.diagnostics.reporter.LogReporter\n```\n\nSpecific query reporter may require additional configuration options. Those options are specified using `options` property. The following example shows a configuration options in case of `RiemannReporter` and it shows how you can configure specific modules to use this reporter:\n\n```\nglobal:\n  systemName: \"smartcat-cassandra-cluster\"\n\n# Reporters\nreporters:\n  - reporter: io.smartcat.cassandra.diagnostics.reporter.LogReporter\n  - reporter: io.smartcat.cassandra.diagnostics.reporter.RiemannReporter\n    options:\n      riemannHost: 127.0.0.1\n      riemannPort: 5555 #Optional\n      batchEventSize: 50 #Optional\n\n# Modules\nmodules:\n  - module: io.smartcat.cassandra.diagnostics.module.requestrate.RequestRateModule\n    measurement: requestRate\n    options:\n      period: 1\n      timeunit: SECONDS\n    reporters:\n      - io.smartcat.cassandra.diagnostics.reporter.LogReporter\n      - io.smartcat.cassandra.diagnostics.reporter.RiemannReporter\n```\n\nBy default all measurements are reported with hostname queried with [InetAddress](http://docs.oracle.com/javase/7/docs/api/java/net/InetAddress.html) java class. If required, hostname can be set using a hostname variable in configuration file:\n\n```\nglobal:\n  systemName: \"smartcat-cassandra-cluster\"\n  hostname: \"test-hostname\"\n\nreporters:\netc...\n```\n\nIt is important to name system under observation because measurements can be collected by various systems. Hostname is not enough, it is easy to imagine one host having Cassandra node and Kafka node both emitting measurement and we want to group those by system. By default \"cassandra-cluster\" will be used but it is advised to override this to have unique grouping of measurements:\n\n```\nglobal:\n  systemName: \"cassandra-cluster\"\n  hostname: \"test-hostname\"\n```\n\n## Information provider\n\nBeing deployed on the node itself, diagnostics connector should provide a connection to the node over JMX by wrapping the Cassandra's NodeProbe class with provides access to all actions and metrics exposed over JMX. This is configured in the `connector` part of the configuration which sits in the root of diagnostics config.\n\n```\nconnector:\n  jmxHost: 127.0.0.1\n  jmxPort: 7199\n  jmxAuthEnabled: false #Optional\n  jmxUsername: username #Optional\n  jmxPassword: password #Optional\n```\nStatus module uses information provided by connector in order to collect info data.\n\n## Control and Configuration API\n\nCassandra Diagnostics exposes a control and configuration API. This API currently offers the following operations:\n\n    - getVersion - returns the actual Cassandra Diagnostics version.\n    - reload - reloads the configuration\n\nThis API is exposed over JMX and HTTP protocols.\n\nThe Diagnostics API JMX MXBean could be found under the following object name:\n\n```\npackage io.smartcat.cassandra.diagnostics.api:type=DiagnosticsApi\n```\n\nThe HTTP API is controlled using the following options in the `global` section in the configuration file:\n\n```\nglobal:\n  # controls if HTTP API is turned on. 'true' by default.\n  httpApiEnabled: true\n  # specifies the host/address part for listening TCP socket. '127.0.0.1' by default.\n  httpApiHost: 127.0.0.1\n  # specifies the port number for the listening TCP socket. '8998' by default.\n  httpApiPort: 8998\n  # if API authorization is enabled, API key must be provided through the 'Authorization' header\n  httpApiAuthEnabled: false\n  # API access key\n  httpApiKey: \"diagnostics-api-key\"\n```\n\nIt implements the following endpoints for mapping HTTP requests to API operations:\n\n- `GET /version` for `getVersion`\n- `POST /reload` for `reload`\n\n## Installation\n\nScript for automated installation is [also available](./bash-installer/README.md).\n\nCassandra Diagnostics consists of the following three components:\n\n- Cassandra Diagnostics Core\n- Cassandra Diagnostics Connector\n- Cassandra Diagnostics Reporter\n\nEvery of these components is packaged into its own JAR file (accompanied with necessary dependencies). These JAR files are available for download on [Maven Central](https://mvnrepository.com/artifact/io.smartcat) and need to be present on the classpath.\n\nPay attention to the fact that Cassandra Diagnostics Connector has to be aligned with the used Cassandra version. For example, `cassandra-diagnostics-connector21` should be used with Cassandra 2.1.\n\nAlso note that more than one Cassandra Diagnostics Reporter can be used at the same time. That means that all respective JAR files have to be put on the classpath. The only exception to this rule is in case of `LogReporter` that is built in Cassandra Diagnostics Core and no Reporter JAR has to be added explicitly.\n\nPlace `cassandra-diagnostics-core-VERSION.jar`, `cassandra-diagnostics-connector21-VERSION.jar` and required Reporter JARs (e.g. `cassandra-diagnostics-reporter-influx-VERSION-all.jar`) into Cassandra `lib` directory.\n\nCreate and place the configuration file `cassandra-diagnostics.yml` into Cassandra's `conf` directory.\nAdd the following line at the end of `conf/cassandra-env.sh`:\n\n```\nJVM_OPTS=\"$JVM_OPTS -javaagent:$CASSANDRA_HOME/lib/cassandra-diagnostics-core-VERSION.jar -Dcassandra.diagnostics.config=cassandra-diagnostics.yml\"\n```\n\n## Usage\n\nUpon Cassandra node start, the Diagnostics agent kicks in and instrument necessary target classes to inject diagnostics additions.\n`LogReporter` repors slow queries in `logs/system.log` at `INFO` level.\nThe dynamic configuration could be inspected/changed using `jconsole` and connecting to `org.apache.cassandra.service.CassandraDaemon`.\n\n## Build and deploy\n\nBuild and deploy process is described [here](BUILDANDDEPLOY.md).\n\n## License and development\n\nCassandra Diagnostics is licensed under the liberal and business-friendly [Apache Licence, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html) and is freely available on GitHub. Cassandra Diagnostics is further released to the repositories of Maven Central and on JCenter. The project is built using [Maven](http://maven.apache.org/). From your shell, cloning and building the project would go something like this:\n\n```\ngit clone https://github.com/smartcat-labs/cassandra-diagnostics.git\ncd cassandra-diagnostics\nmvn package\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmartcat-labs%2Fcassandra-diagnostics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmartcat-labs%2Fcassandra-diagnostics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmartcat-labs%2Fcassandra-diagnostics/lists"}