| Name | otel-cli JSON |
| Version |
0.4.0
JSON |
| download |
| home_page | |
| Summary | CLI for OpenTelemetry Traces and Metrics in Python |
| upload_time | 2023-01-30 10:29:50 |
| maintainer | |
| docs_url | None |
| author | Moshi Binyamini |
| requires_python | >=3.7,<4.0 |
| license | |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# opentelemetry-cli: human-friendly OpenTelemetry CLI
[](https://github.com/dell/opentelemetry-cli/blob/main/LICENSE)
[](https://hub.docker.com/r/dell/opentelemetry-cli)
[](https://pypi.org/project/otel-cli/)
[](https://github.com/psf/black)
[](https://codecov.io/gh/dell/opentelemetry-cli)
[](https://github.com/dell/opentelemetry-cli/actions/workflows/docker-publish.yml)
[](https://github.com/dell/opentelemetry-cli/actions/workflows/tests.yml)
[](https://gitmoji.dev/)
Provides a CLI for crafting and sending telemetry data over OTLP (OpenTelemetry Line Protocol).
## Requirements
## Installation
There are several ways of running this CLI.
### Docker
```sh
docker pull opentelemetry-cli:<version>
```
You can specify a version like `0.2.0` or use `latest` to get the most up-to-date version.
Run latest version of the CLI in a container:
```sh
# set OTEL_EXPORTER_OTLP_ENDPOINT to your OTel collector instance
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317
docker run --rm -e OTEL_EXPORTER_OTLP_ENDPOINT opentelemetry-cli:latest --help
```
Replace `--help` with any `otel` command, without `otel` itself.
### PyPI
```sh
pip install otel-cli
```
## Usage
First, define `OTEL_EXPORTER_OTLP_ENDPOINT` in your shell and set it to the OTLP collector instance you want to use.
For a local collector, set this to `http://127.0.0.1:4317` like so:
```sh
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317
```
### Spans
To send a span, run:
```sh
otel span "span name"
```
To set a different service name, use the `--service` flag:
```sh
otel span --service "My Service" "span name"
```
You can also pass custom start and end dates. These should be *nanoseconds* since the epoch:
```sh
SPAN_START_DATE=$(date --date "2 minutes ago" +%s%N)
SPAN_END_DATE=$(date +%s%N)
otel span --start "$SPAN_START_DATE" --end "$SPAN_END_DATE" "span name"
```
By default, spans are reported with a status of `UNKNOWN`. To pass a different status, use the `--status` option:
```sh
otel span --status OK "successful span"
otel span --status ERROR "failed span"
```
To add attributes to spans, use the `--attribute|-a` option. It accepts attributes in a `key=value` format. Use multiple instances of this option to send multiple attributes.
```sh
otel span -a "my.foo=bar" -a "my.bar=baz" "span name"
```
otel will create a random trace ID and span ID. You can override those:
```sh
otel span --trace-id "4d999706756fd1859345f8dc6d0af218" --span-id "ac2a3b2b19ac602d"
```
#### Sending multiple spans in a trace
To create a single trace with one root span and multiple child spans, we first need to generate a trace ID for the entire trace and a span ID for the parent span. Use `otel generate` to create those:
```sh
TRACE_ID=$(otel generate trace_id)
PARENT_SPAN=$(otel generate span_id)
```
Then, when creating children span, we pass this information in the format of a `TRACEPARENT`:
```sh
TRACEPARENT="00-${TRACE_ID}-${PARENT_SPAN}-01"
otel span --traceparent "$TRACEPARENT" "Child A Name"
otel span --traceparent "$TRACEPARENT" "Child B Name"
```
Finally, send the parent span using the pre-generated IDs:
```sh
otel span --trace-id "$TRACE_ID" --span-id "$PARENT_SPAN" "Parent Span Name"
```
### Metrics
Use `otel metric` to send metric data. The following metric types are currently supported:
- Counter
- UpDownCounter
#### Counter
Counters are metrics that can count only up.
By specifying just the counter name, it will be incremented by 1:
```sh
otel metric counter my-counter
```
You can specify a different value to increase by. For example, this will increase the counter by 1024:
```sh
otel metric counter total-bytes 1024
```
Counters support attributes just like spans, using the `-a|--attribute` option.
```sh
otel metric counter my-counter -a "host.name=localhost"
```
By default, attributes are strings. You can set them to other types by using one of the following prefixes:
- `int:` - value will be converted to an integer.
- `float:` - value will be converted to a floating point number.
- `bool:` - value will be converted to a boolean.
- Values of `y`, `yes`, `t`, `true`, `on`, and `1` are converted to `True`.
- Values of `n`, `no`, `f`, `false`, `off`, and `0` are converted to `False`.
- Values are __not__ case-sensitive.
Example:
```sh
otel metric counter my-counter \
-a "key1=just a string" \
-a "int:key2=10" \
-a "float:key3=3.14" \
-a "bool:key4=YES"
```
#### UpDownCounter
UpDownCounters are metrics that count up or down.
If not given a value, the UpDownCounter will increment by one:
```sh
otel metric updown queue-length
```
You can specify a different value to increase by. For example, this will increase the counter by 1024:
```sh
otel metric updown my-updowncounter 1024
```
To decrease the counter number, pass a negative number like so:
```sh
otel metric updown queue-length -1
```
## Packaging
This project uses [poetry](https://python-poetry.org/) to manage dependencies, build, etc.
Raw data
{
"_id": null,
"home_page": "",
"name": "otel-cli",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Moshi Binyamini",
"author_email": "moshi.binyamini@dell.com",
"download_url": "https://files.pythonhosted.org/packages/57/7d/782a92b3c35ca120f15ab4f3c001baeac09f8c36c1d555a9187fb8431f61/otel_cli-0.4.0.tar.gz",
"platform": null,
"description": "# opentelemetry-cli: human-friendly OpenTelemetry CLI\n\n[](https://github.com/dell/opentelemetry-cli/blob/main/LICENSE)\n[](https://hub.docker.com/r/dell/opentelemetry-cli)\n[](https://pypi.org/project/otel-cli/)\n[](https://github.com/psf/black)\n[](https://codecov.io/gh/dell/opentelemetry-cli)\n[](https://github.com/dell/opentelemetry-cli/actions/workflows/docker-publish.yml)\n[](https://github.com/dell/opentelemetry-cli/actions/workflows/tests.yml)\n[](https://gitmoji.dev/)\n\nProvides a CLI for crafting and sending telemetry data over OTLP (OpenTelemetry Line Protocol).\n\n## Requirements\n\n## Installation\n\nThere are several ways of running this CLI.\n\n### Docker\n\n```sh\ndocker pull opentelemetry-cli:<version>\n```\n\nYou can specify a version like `0.2.0` or use `latest` to get the most up-to-date version.\n\nRun latest version of the CLI in a container:\n\n```sh\n# set OTEL_EXPORTER_OTLP_ENDPOINT to your OTel collector instance\nexport OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317\ndocker run --rm -e OTEL_EXPORTER_OTLP_ENDPOINT opentelemetry-cli:latest --help\n```\n\nReplace `--help` with any `otel` command, without `otel` itself.\n\n### PyPI\n\n```sh\npip install otel-cli\n```\n\n## Usage\n\nFirst, define `OTEL_EXPORTER_OTLP_ENDPOINT` in your shell and set it to the OTLP collector instance you want to use.\nFor a local collector, set this to `http://127.0.0.1:4317` like so:\n\n```sh\nexport OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317\n```\n\n### Spans\n\nTo send a span, run:\n\n```sh\notel span \"span name\"\n```\n\nTo set a different service name, use the `--service` flag:\n\n```sh\notel span --service \"My Service\" \"span name\"\n```\n\nYou can also pass custom start and end dates. These should be *nanoseconds* since the epoch:\n\n```sh\nSPAN_START_DATE=$(date --date \"2 minutes ago\" +%s%N)\nSPAN_END_DATE=$(date +%s%N)\notel span --start \"$SPAN_START_DATE\" --end \"$SPAN_END_DATE\" \"span name\"\n```\n\nBy default, spans are reported with a status of `UNKNOWN`. To pass a different status, use the `--status` option:\n\n```sh\notel span --status OK \"successful span\"\notel span --status ERROR \"failed span\"\n```\n\nTo add attributes to spans, use the `--attribute|-a` option. It accepts attributes in a `key=value` format. Use multiple instances of this option to send multiple attributes.\n\n```sh\notel span -a \"my.foo=bar\" -a \"my.bar=baz\" \"span name\"\n```\n\notel will create a random trace ID and span ID. You can override those:\n\n```sh\notel span --trace-id \"4d999706756fd1859345f8dc6d0af218\" --span-id \"ac2a3b2b19ac602d\"\n```\n\n#### Sending multiple spans in a trace\n\nTo create a single trace with one root span and multiple child spans, we first need to generate a trace ID for the entire trace and a span ID for the parent span. Use `otel generate` to create those:\n\n```sh\nTRACE_ID=$(otel generate trace_id)\nPARENT_SPAN=$(otel generate span_id)\n```\n\nThen, when creating children span, we pass this information in the format of a `TRACEPARENT`:\n\n```sh\nTRACEPARENT=\"00-${TRACE_ID}-${PARENT_SPAN}-01\"\notel span --traceparent \"$TRACEPARENT\" \"Child A Name\"\notel span --traceparent \"$TRACEPARENT\" \"Child B Name\"\n```\n\nFinally, send the parent span using the pre-generated IDs:\n\n```sh\notel span --trace-id \"$TRACE_ID\" --span-id \"$PARENT_SPAN\" \"Parent Span Name\"\n```\n\n### Metrics\n\nUse `otel metric` to send metric data. The following metric types are currently supported:\n\n- Counter\n- UpDownCounter\n\n#### Counter\n\nCounters are metrics that can count only up.\nBy specifying just the counter name, it will be incremented by 1:\n\n```sh\notel metric counter my-counter\n```\n\nYou can specify a different value to increase by. For example, this will increase the counter by 1024:\n\n```sh\notel metric counter total-bytes 1024\n```\n\nCounters support attributes just like spans, using the `-a|--attribute` option.\n\n```sh\notel metric counter my-counter -a \"host.name=localhost\"\n```\n\nBy default, attributes are strings. You can set them to other types by using one of the following prefixes:\n\n- `int:` - value will be converted to an integer.\n- `float:` - value will be converted to a floating point number.\n- `bool:` - value will be converted to a boolean.\n - Values of `y`, `yes`, `t`, `true`, `on`, and `1` are converted to `True`.\n - Values of `n`, `no`, `f`, `false`, `off`, and `0` are converted to `False`.\n - Values are __not__ case-sensitive.\n\nExample:\n\n```sh\notel metric counter my-counter \\\n -a \"key1=just a string\" \\\n -a \"int:key2=10\" \\\n -a \"float:key3=3.14\" \\\n -a \"bool:key4=YES\"\n```\n\n#### UpDownCounter\n\nUpDownCounters are metrics that count up or down.\nIf not given a value, the UpDownCounter will increment by one:\n\n```sh\notel metric updown queue-length\n```\n\nYou can specify a different value to increase by. For example, this will increase the counter by 1024:\n\n```sh\notel metric updown my-updowncounter 1024\n```\n\nTo decrease the counter number, pass a negative number like so:\n\n```sh\notel metric updown queue-length -1\n```\n\n## Packaging\nThis project uses [poetry](https://python-poetry.org/) to manage dependencies, build, etc.\n",
"bugtrack_url": null,
"license": "",
"summary": "CLI for OpenTelemetry Traces and Metrics in Python",
"version": "0.4.0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4504c578e67d7c94e9b5e8f31273c24dc5d3029aed16b609494352abc6a2f75e",
"md5": "0ded99a64bc50f9d5e88546b47a02585",
"sha256": "1fe74d223684a099824f72df44436e88bf069d5caff4bc5f5e54d8b5d933d4a6"
},
"downloads": -1,
"filename": "otel_cli-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0ded99a64bc50f9d5e88546b47a02585",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 9693,
"upload_time": "2023-01-30T10:29:49",
"upload_time_iso_8601": "2023-01-30T10:29:49.021346Z",
"url": "https://files.pythonhosted.org/packages/45/04/c578e67d7c94e9b5e8f31273c24dc5d3029aed16b609494352abc6a2f75e/otel_cli-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "577d782a92b3c35ca120f15ab4f3c001baeac09f8c36c1d555a9187fb8431f61",
"md5": "8dc4a29871dc5a2a82470da4d25df373",
"sha256": "d03b4aee32ee4cb4ab019bf2beb4e8b2019e6bffaccf53941b40749319e5bc13"
},
"downloads": -1,
"filename": "otel_cli-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "8dc4a29871dc5a2a82470da4d25df373",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 10751,
"upload_time": "2023-01-30T10:29:50",
"upload_time_iso_8601": "2023-01-30T10:29:50.480396Z",
"url": "https://files.pythonhosted.org/packages/57/7d/782a92b3c35ca120f15ab4f3c001baeac09f8c36c1d555a9187fb8431f61/otel_cli-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-30 10:29:50",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "otel-cli"
}
