MetricQ Tools
=============
[](https://github.com/metricq/metricq-tools/actions/workflows/package.yml)
[](https://pypi.org/project/metricq-tools/)
Tools and utility scripts to utilize, monitor, and administrate a MetricQ network.
Common command line options
---------------------------
```
--server URL MetricQ server URL. [required]
--token CLIENT_TOKEN A token to identify this client on the MetricQ
network. [default: depends on the tool]
-v, --verbosity LVL Either CRITICAL, ERROR, WARNING, INFO or DEBUG
--version Show the version and exit.
--help Show this message and exit.
```
All options for these tools can be passed as environment variables prefixed with `METRICQ_`,
i.e., `METRICQ_SERVER=amqps://...`.
You can also create a `.metricq` file in the current or home directory that contains environment variable settings in the same format.
Some options, including server and token, can contain placeholders for `$USER` and `$HOST`.
User tools
----------
`metricq-energy`
----------------
Run a command and calculate the energy consumption of a metric during this execution.
```
Usage: metricq-energy [OPTIONS] COMMAND...
Get a single energy value for a metric during the execution of the given
command. This value is just the integral of the metric over the time the
command was running.
The integral is calculated as the product of the arithmetic mean of all
values times the runtime of the given command. For the result to be
accurate, the metric should have updates in regular intervals and there
should be a sufficient number of values for the duration of the command.
Options:
-m, --metric TEXT [required]
--expires INTEGER Queue expiration time in seconds. Set this value to
the maximum time the command is expected to run.
```
`metricq-slurm`
---------------
Get the energy consumption for SLURM jobs.
```
Usage: metricq-slurm [OPTIONS]
Get an energy value for a slurm job given its job id.
This only works for exclusive jobs.
Options:
-m, --metric TEXT Pattern for per-metric power consumption. $HOST will
be replaced with the host(s) running the job. The
metric is assumed to be in W (watts). [required]
-j, --jobs TEXT job(.step) or list of job(.steps) as per sacct
[required]
```
`metricq-summary`
-----------------
Run a command and collect statistics about a given metric during this execution.
```
Usage: metricq-summary [OPTIONS] COMMAND...
Live metric data analysis and inspection on the MetricQ network.
Consumes new data points for the given metric as they are submitted to the
network, prints a statistical overview on exit.
Options:
-i, --intervals-histogram / -I, --no-intervals-histogram
Show an histogram of the observed
distribution of durations between data
points.
-h, --values-histogram / -H, --no-values-histogram
Show an histogram of the observed metric
values.
-d, --print-data-points / -D, --no-print-data-points
-s, --print-statistics / -S, --no-print-statistics
-m, --metric TEXT [required]
```
Administrator tools
-------------------
These tools are intended for debugging and monitoring MetricQ networks.
`metricq-check`
---------------
Uses the aggregation of persisted metric values to quickly check, if it contains non-finite values like +/-inf and NaN.
```
Usage: metricq-check [OPTIONS]
Check metrics for non-finite values.
```
`metricq-discover`
------------------
Send an RPC broadcast on the MetricQ network and wait for replies from clients that are currently online.
```
Usage: metricq-discover [OPTIONS]
Send an RPC broadcast on the MetricQ network and wait for replies from online
clients.
Options:
-d, --diff JSON_FILE Show a diff to a list of previously discovered
clients (produced with --format=json)
-t, --timeout DURATION Wait at most this long for replies.
--format (pretty|json) Print results in this format [default:
(pretty)]
--ignore (error-responses) Messages to ignore.
```
`metricq-inspect`
-----------------
Consumes new data points for the given metric as they are submitted to the network, prints a statistical overview on exit.
```
Usage: metricq-inspect [OPTIONS] METRIC
Live metric data analysis and inspection on the MetricQ network.
Consumes new data points for the given metric as they are submitted to the
network, prints a statistical overview on exit.
Options:
-i, --intervals-histogram / -I, --no-intervals-histogram
Show an histogram of the observed
distribution of durations between data
points.
-h, --values-histogram / -H, --no-values-histogram
Show an histogram of the observed metric
values.
-c, --chunk-sizes-histogram / -C, --no-chunk-sizes-histogram
Show an histogram of the observed chunk
sizes of all messages received.
-d, --print-data-points / -D, --no-print-data-points
```
`metricq-send`
--------------
Send a single time-value pair for the given metric.
```
Usage: metricq-send [OPTIONS] METRIC VALUE
Send a single time-value pair for the given metric.
Options:
--timestamp TIMESTAMP Timestamp to send. [default: (now)]
```
`metricq-spy`
-------------
Obtain metadata and storage location for a set of metrics.
```
Usage: metricq-spy [OPTIONS] METRICS...
Obtain metadata and storage location for a set of metrics.
Options:
--format (pretty|json) Print results in this format [default: (pretty)]
```
Raw data
{
"_id": null,
"home_page": "https://github.com/metricq/metricq-tools",
"name": "metricq-tools",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "",
"author": "TU Dresden",
"author_email": "",
"download_url": "",
"platform": null,
"description": "MetricQ Tools\n=============\n\n\n[](https://github.com/metricq/metricq-tools/actions/workflows/package.yml)\n\n[](https://pypi.org/project/metricq-tools/)\n\n\nTools and utility scripts to utilize, monitor, and administrate a MetricQ network.\n\n\nCommon command line options\n---------------------------\n\n```\n --server URL MetricQ server URL. [required]\n --token CLIENT_TOKEN A token to identify this client on the MetricQ\n network. [default: depends on the tool]\n -v, --verbosity LVL Either CRITICAL, ERROR, WARNING, INFO or DEBUG\n --version Show the version and exit.\n --help Show this message and exit.\n```\n\nAll options for these tools can be passed as environment variables prefixed with `METRICQ_`,\ni.e., `METRICQ_SERVER=amqps://...`.\nYou can also create a `.metricq` file in the current or home directory that contains environment variable settings in the same format.\nSome options, including server and token, can contain placeholders for `$USER` and `$HOST`.\n\n\nUser tools\n----------\n\n`metricq-energy`\n----------------\n\nRun a command and calculate the energy consumption of a metric during this execution.\n\n```\nUsage: metricq-energy [OPTIONS] COMMAND...\n\n Get a single energy value for a metric during the execution of the given\n command. This value is just the integral of the metric over the time the\n command was running.\n\n The integral is calculated as the product of the arithmetic mean of all\n values times the runtime of the given command. For the result to be\n accurate, the metric should have updates in regular intervals and there\n should be a sufficient number of values for the duration of the command.\n\nOptions:\n -m, --metric TEXT [required]\n --expires INTEGER Queue expiration time in seconds. Set this value to\n the maximum time the command is expected to run.\n```\n\n`metricq-slurm`\n---------------\n\nGet the energy consumption for SLURM jobs.\n\n```\nUsage: metricq-slurm [OPTIONS]\n\n Get an energy value for a slurm job given its job id.\n\n This only works for exclusive jobs.\n\nOptions:\n -m, --metric TEXT Pattern for per-metric power consumption. $HOST will\n be replaced with the host(s) running the job. The\n metric is assumed to be in W (watts). [required]\n -j, --jobs TEXT job(.step) or list of job(.steps) as per sacct\n [required]\n```\n\n`metricq-summary`\n-----------------\n\nRun a command and collect statistics about a given metric during this execution.\n\n```\nUsage: metricq-summary [OPTIONS] COMMAND...\n\n Live metric data analysis and inspection on the MetricQ network.\n\n Consumes new data points for the given metric as they are submitted to the\n network, prints a statistical overview on exit.\n\nOptions:\n -i, --intervals-histogram / -I, --no-intervals-histogram\n Show an histogram of the observed\n distribution of durations between data\n points.\n -h, --values-histogram / -H, --no-values-histogram\n Show an histogram of the observed metric\n values.\n -d, --print-data-points / -D, --no-print-data-points\n -s, --print-statistics / -S, --no-print-statistics\n -m, --metric TEXT [required]\n```\n\nAdministrator tools\n-------------------\n\nThese tools are intended for debugging and monitoring MetricQ networks.\n\n`metricq-check`\n---------------\n\nUses the aggregation of persisted metric values to quickly check, if it contains non-finite values like +/-inf and NaN.\n\n```\nUsage: metricq-check [OPTIONS]\n\n Check metrics for non-finite values.\n```\n\n`metricq-discover`\n------------------\n\nSend an RPC broadcast on the MetricQ network and wait for replies from clients that are currently online.\n\n```\nUsage: metricq-discover [OPTIONS]\n\n Send an RPC broadcast on the MetricQ network and wait for replies from online\n clients.\n\nOptions:\n -d, --diff JSON_FILE Show a diff to a list of previously discovered\n clients (produced with --format=json)\n -t, --timeout DURATION Wait at most this long for replies.\n --format (pretty|json) Print results in this format [default:\n (pretty)]\n --ignore (error-responses) Messages to ignore.\n```\n\n`metricq-inspect`\n-----------------\n\nConsumes new data points for the given metric as they are submitted to the network, prints a statistical overview on exit.\n\n```\nUsage: metricq-inspect [OPTIONS] METRIC\n\n Live metric data analysis and inspection on the MetricQ network.\n\n Consumes new data points for the given metric as they are submitted to the\n network, prints a statistical overview on exit.\n\nOptions:\n -i, --intervals-histogram / -I, --no-intervals-histogram\n Show an histogram of the observed\n distribution of durations between data\n points.\n -h, --values-histogram / -H, --no-values-histogram\n Show an histogram of the observed metric\n values.\n -c, --chunk-sizes-histogram / -C, --no-chunk-sizes-histogram\n Show an histogram of the observed chunk\n sizes of all messages received.\n -d, --print-data-points / -D, --no-print-data-points\n```\n\n`metricq-send`\n--------------\n\nSend a single time-value pair for the given metric.\n\n```\nUsage: metricq-send [OPTIONS] METRIC VALUE\n\n Send a single time-value pair for the given metric.\n\nOptions:\n --timestamp TIMESTAMP Timestamp to send. [default: (now)]\n```\n\n`metricq-spy`\n-------------\n\nObtain metadata and storage location for a set of metrics.\n\n```\nUsage: metricq-spy [OPTIONS] METRICS...\n\n Obtain metadata and storage location for a set of metrics.\n\nOptions:\n --format (pretty|json) Print results in this format [default: (pretty)]\n```\n\n",
"bugtrack_url": null,
"license": "GPL3",
"summary": "Useful scripts to manage and inspect a MetricQ instance",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/metricq/metricq-tools"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2e78990b6a6a88676b6e1ed6a10910f61651da55fd6b7bf1d974a74ed88980c4",
"md5": "8deada17c4e89641b788e385101a1f4f",
"sha256": "245cf3c43bee77710509cbbe44abf88184f8b1ed2b202aad0c9cd3be7292f791"
},
"downloads": -1,
"filename": "metricq_tools-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8deada17c4e89641b788e385101a1f4f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 34820,
"upload_time": "2023-06-09T13:34:35",
"upload_time_iso_8601": "2023-06-09T13:34:35.354899Z",
"url": "https://files.pythonhosted.org/packages/2e/78/990b6a6a88676b6e1ed6a10910f61651da55fd6b7bf1d974a74ed88980c4/metricq_tools-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-09 13:34:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "metricq",
"github_project": "metricq-tools",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "metricq-tools"
}
JSON
