-
Notifications
You must be signed in to change notification settings - Fork 2.4k
/
README.md
197 lines (123 loc) · 7.66 KB
/
README.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
# JMX Receiver
<!-- status autogenerated section -->
| Status | |
| ------------- |-----------|
| Stability | [alpha]: metrics |
| Distributions | [contrib] |
| Issues | [![Open issues](https://img.shields.io/github/issues-search/open-telemetry/opentelemetry-collector-contrib?query=is%3Aissue%20is%3Aopen%20label%3Areceiver%2Fjmx%20&label=open&color=orange&logo=opentelemetry)](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues?q=is%3Aopen+is%3Aissue+label%3Areceiver%2Fjmx) [![Closed issues](https://img.shields.io/github/issues-search/open-telemetry/opentelemetry-collector-contrib?query=is%3Aissue%20is%3Aclosed%20label%3Areceiver%2Fjmx%20&label=closed&color=blue&logo=opentelemetry)](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues?q=is%3Aclosed+is%3Aissue+label%3Areceiver%2Fjmx) |
| [Code Owners](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/CONTRIBUTING.md#becoming-a-code-owner) | [@rmfitzpatrick](https://www.github.com/rmfitzpatrick) |
[alpha]: https://github.com/open-telemetry/opentelemetry-collector#alpha
[contrib]: https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-contrib
<!-- end autogenerated section -->
### Overview
The JMX Receiver will work in conjunction with the [OpenTelemetry JMX Metric Gatherer](https://github.com/open-telemetry/opentelemetry-java-contrib/blob/main/jmx-metrics/README.md)
to report metrics from a target MBean server using a built-in `otel` helper-utilizing Groovy script.
### Details
This receiver will launch a child JRE process running the JMX Metric Gatherer configured with your specified JMX
connection information and target Groovy script. It then reports metrics to an implicitly created OTLP receiver.
In order to use you will need to download the most [recent release](https://github.com/open-telemetry/opentelemetry-java-contrib/releases)
of the JMX Metric Gatherer JAR and configure the receiver with its path. It is assumed that the JRE is
available on your system.
# Configuration
Note: this receiver is in alpha and functionality and configuration fields are subject to change.
Example configuration:
```yaml
receivers:
jmx:
jar_path: /opt/opentelemetry-java-contrib-jmx-metrics.jar
endpoint: my_jmx_host:12345
target_system: jvm
collection_interval: 10s
initial_delay: 1s
# optional: the same as specifying OTLP receiver endpoint.
otlp:
endpoint: mycollectorotlpreceiver:4317
username: my_jmx_username
# determined by the environment variable value
password: ${env:MY_JMX_PASSWORD}
resource_attributes:
my.attr: my.value
my.other.attr: my.other.value
log_level: info
additional_jars:
- /path/to/other.jar
```
### jar_path (default: `/opt/opentelemetry-java-contrib-jmx-metrics.jar`)
The path for the JMX Metric Gatherer uber JAR to run. This must represent a released version 1.9+ of the jar,
which can be downloaded from [github](https://github.com/open-telemetry/opentelemetry-java-contrib/releases).
If a non-released version is required, you can specify a custom version by providing the sha256 hash of your
custom version of the jar during collector build time using the `ldflags` option.
```bash
go build -ldflags "-X github.com/open-telemetry/opentelemetry-collector-contrib/receiver/jmxreceiver.MetricsGathererHash=<sha256hash>" ...
```
### endpoint
The [JMX Service URL](https://docs.oracle.com/javase/8/docs/api/javax/management/remote/JMXServiceURL.html) or host
and port used to construct the Service URL the Metric Gatherer's JMX client should use. Value must be in the form of
`service:jmx:<protocol>:<sap>` or `host:port`. Values in `host:port` form will be used to create a Service URL of
`service:jmx:rmi:///jndi/rmi://<host>:<port>/jmxrmi`.
When in or coerced to `service:jmx:<protocol>:<sap>` form, corresponds to the `otel.jmx.service.url` property.
_Required._
### target_system
The built-in target system (or systems) metric gatherer script to run.
Must be a subset of: `"activemq"`, `"cassandra"`, `"hbase"`, `"hadoop"`, `"jetty"`, `"jvm"`, `"kafka"`, `"kafka-consumer"`, `"kafka-producer"`, `"solr"`, `"tomcat"`, `"wildfly"`.
If additional target systems must be supported (because of a custom JMX metrics gatherer jar configured using the
`MetricsGathererHash` build time config), they can be added with another build time flag.
```bash
go build -ldflags "-X github.com/open-telemetry/opentelemetry-collector-contrib/receiver/jmxreceiver.MetricsGathererHash=<sha256hash>
-X github.com/open-telemetry/opentelemetry-collector-contrib/receiver/jmxreceiver.AdditionalTargetSystems=newtarget,othernewtarget" ...
```
Corresponds to the `otel.jmx.target.system` property.
### collection_interval (default: `10s`)
The interval time for the Groovy script to be run and metrics to be exported by the JMX Metric Gatherer within the persistent JRE process.
Corresponds to the `otel.jmx.interval.milliseconds` property.
### initial_delay (default: `1s`)
Defines how long this receiver waits before starting.
### username
The username to use for JMX authentication.
Corresponds to the `otel.jmx.username` property.
### password
The password to use for JMX authentication.
Corresponds to the `otel.jmx.password` property.
### otlp.endpoint (default: `0.0.0.0:<random open port>`)
The otlp exporter endpoint to which to listen and submit metrics.
Corresponds to the `otel.exporter.otlp.endpoint` property.
### otlp.timeout (default: `5s`)
The otlp exporter request timeout.
Corresponds to the `otel.exporter.otlp.metric.timeout` property.
### otlp.headers
The headers to include in otlp metric submission requests.
Corresponds to the `otel.exporter.otlp.metadata` property.
### keystore_path
The keystore path is required if SSL is enabled on the target JVM.
Corresponds to the `javax.net.ssl.keyStore` property.
### keystore_password
The keystore file password if required by SSL.
Corresponds to the `javax.net.ssl.keyStorePassword` property.
### keystore_type
The keystore type if required by SSL.
Corresponds to the `javax.net.ssl.keyStoreType` property.
### truststore_path
The truststore path if the SSL profile is required.
Corresponds to the `javax.net.ssl.trustStore` property.
### truststore_password
The truststore file password if required by SSL.
Corresponds to the `javax.net.ssl.trustStorePassword` property.
### truststore_type
The truststore type if required by SSL.
Corresponds to the `javax.net.ssl.trustStoreType` property.
### remote_profile
Supported JMX remote profiles are TLS in combination with SASL profiles: SASL/PLAIN, SASL/DIGEST-MD5 and SASL/CRAM-MD5.
Should be one of: `"SASL/PLAIN"`, `"SASL/DIGEST-MD5"`, `"SASL/CRAM-MD5"`, `"TLS SASL/PLAIN"`, `"TLS SASL/DIGEST-MD5"`,
or `"TLS SASL/CRAM-MD5"`, though no enforcement is applied.
Corresponds to the `otel.jmx.remote.profile` property.
### realm
The realm, as required by remote profile SASL/DIGEST-MD5.
Corresponds to the `otel.jmx.realm` property.
### additional_jars
Additional JARs to be included in the java command classpath. This is currently only used for support for `wildfly`, where the Additional Jar should be a version of the jboss-client jar found on your wildfly installation.
### resource_attributes
Map of resource attributes that will be applied to any metrics emitted from the metrics gatherer.
Corresponds to the `otel.resource.attributes` property.
### log_level
SLF4J log level for the JMX metrics gatherer. Must be one of: `"trace"`, `"debug"`, `"info"`, `"warn"`, `"error"`, `"off"`. If not provided, will attempt to match to the current log level of the collector.
Corresponds to the `org.slf4j.simpleLogger.defaultLogLevel` property.