SOLR-9959: Ref Guide changes for JMX and metric name changes

This commit is contained in:
Cassandra Targett 2017-09-20 10:27:59 -05:00
parent 45b18790c4
commit 2351e3ef1f
4 changed files with 139 additions and 116 deletions

View File

@ -135,11 +135,11 @@ See the section <<spatial-search.adoc#spatial-search,Spatial Search>> for more i
=== JMX Support and MBeans === JMX Support and MBeans
* The `<jmx>` element in `solrconfig.xml` has been removed in favor of `<metrics><reporter>` elements defined in `solr.xml`. * The `<jmx>` element in `solrconfig.xml` has been removed in favor of `<metrics><reporter>` elements defined in `solr.xml`.
+ +
Limited back-compatibility is offered by automatically adding a default instance of `SolrJmxReporter` if it's missing, AND when a local MBean server is found (which can be activated either via `ENABLE_REMOTE_JMX_OPTS` in `solr.in.sh` or via system properties, e.g., `-Dcom.sun.management.jmxremote`). This default instance exports all Solr metrics from all registries as hierarchical MBeans. Limited back-compatibility is offered by automatically adding a default instance of `SolrJmxReporter` if it's missing AND when a local MBean server is found. A local MBean server can be activated either via `ENABLE_REMOTE_JMX_OPTS` in `solr.in.sh` or via system properties, e.g., `-Dcom.sun.management.jmxremote`. This default instance exports all Solr metrics from all registries as hierarchical MBeans.
+ +
This behavior can be also disabled by specifying a `SolrJmxReporter` configuration with a boolean init argument `enabled` set to `false`. For a more fine-grained control users should explicitly specify at least one `SolrJmxReporter` configuration. This behavior can be also disabled by specifying a `SolrJmxReporter` configuration with a boolean init argument `enabled` set to `false`. For a more fine-grained control users should explicitly specify at least one `SolrJmxReporter` configuration.
+ +
See also the section <<metrics-reporting.adoc#the-metrics-reporters-element,The <metrics><reporters> Element>>, which describes how to set up Metrics Reporters in `solr.xml`. See also the section <<metrics-reporting.adoc#the-metrics-reporters-element,The <metrics><reporters> Element>>, which describes how to set up Metrics Reporters in `solr.xml`. Note that back-compatibility support may be removed in Solr 8.
* MBean names and attributes now follow the hierarchical names used in metrics. This is reflected also in `/admin/mbeans` and `/admin/plugins` output, and can be observed in the UI Plugins tab, because now all these APIs get their data from the metrics API. The old (mostly flat) JMX view has been removed. * MBean names and attributes now follow the hierarchical names used in metrics. This is reflected also in `/admin/mbeans` and `/admin/plugins` output, and can be observed in the UI Plugins tab, because now all these APIs get their data from the metrics API. The old (mostly flat) JMX view has been removed.

View File

@ -200,17 +200,21 @@ The JMX Reporter uses the `org.apache.solr.metrics.reporters.SolrJmxReporter` cl
It takes the following arguments: It takes the following arguments:
* *domain* - (optional str) JMX domain name. If not specified then registry name will be used. * *domain* - (optional string) JMX domain name. If not specified then the registry name will be used.
* *serviceUrl* - (optional str) service URL for a JMX server. If not specified then the default platform MBean server will be used. * *serviceUrl* - (optional string) The service URL for a JMX server. If not specified, Solr will attempt to discover if the JVM has an MBean server and will use that address. See below for additional information on this.
* *agentId* - (optional str) agent ID for a JMX server. Note: either `serviceUrl` or `agentId` can be specified but not both - if both are specified then the default MBean server will be used. * *agentId* - (optional string) The agent ID for a JMX server. Note either `serviceUrl` or `agentId` can be specified but not both - if both are specified then the default MBean server will be used.
Object names created by this reporter are hierarchical, dot-separated but also properly structured to form corresponding hierarchies in e.g., JConsole. This hierarchy consists of the following elements in the top-down order: Object names created by this reporter are hierarchical, dot-separated but also properly structured to form corresponding hierarchies in e.g., JConsole. This hierarchy consists of the following elements in the top-down order:
* registry name (e.g., `solr.core.collection1.shard1.replica1`. Dot-separated registry names are also split into ObjectName hierarchy levels, so that metrics for this registry will be shown under `/solr/core/collection1/shard1/replica1` in JConsole, with each domain part being assigned to `dom1, dom2, ... domN` property. * registry name (e.g., `solr.core.collection1.shard1.replica1`). Dot-separated registry names are also split into ObjectName hierarchy levels, so that metrics for this registry will be shown under `/solr/core/collection1/shard1/replica1` in JConsole, with each domain part being assigned to `dom1, dom2, ... domN` property.
* reporter name (the value of reporter's `name` attribute) * reporter name (the value of reporter's `name` attribute)
* category, scope and name for request handlers * category, scope and name for request handlers
* or additional `name1, name2, ... nameN` elements for metrics from other components. * or additional `name1, name2, ... nameN` elements for metrics from other components.
The JMX Reporter replaces the JMX functionality available in Solr versions before 7.0. If you have upgraded from an earlier version and have an MBean Server running when Solr starts, Solr will automatically discover the location of the local MBean server and use a default configuration for the SolrJmxReporter.
You can start a local MBean server with a system property at startup by adding `-Dcom.sun.management.jmxremote` to your start command. This will not add the reporter configuration to `solr.xml`, so if you enable it with a system property, you must always start Solr with the system property or JMX will not be enabled in subsequent starts.
=== SLF4J Reporter === SLF4J Reporter
The SLF4J Reporter uses the `org.apache.solr.metrics.reporters.SolrSlf4jReporter` class. The SLF4J Reporter uses the `org.apache.solr.metrics.reporters.SolrSlf4jReporter` class.
@ -340,13 +344,14 @@ prefix:: The first characters of metric name that will filter the metrics return
property:: Allows requesting only this metric from any compound metric. Multiple `property` parameters can be combined to act as an OR request. For example, to only get the 99th and 999th percentile values from all metric types and groups, you can add `&property=p99_ms&property=p999_ms` to your request. This can be combined with `group`, `type`, and `prefix` as necessary. property:: Allows requesting only this metric from any compound metric. Multiple `property` parameters can be combined to act as an OR request. For example, to only get the 99th and 999th percentile values from all metric types and groups, you can add `&property=p99_ms&property=p999_ms` to your request. This can be combined with `group`, `type`, and `prefix` as necessary.
key:: fully-qualified metric name, which specifies one concrete metric instance (parameter can be key:: fully-qualified metric name, which specifies one concrete metric instance (parameter can be
specified multiple times to retrieve multiple concrete metrics). *NOTE: when this parameter is used other specified multiple times to retrieve multiple concrete metrics). *NOTE: when this parameter is used, other
selection methods listed above are ignored.* Fully-qualified name consists of registry name, colon and selection methods listed above are ignored.* Fully-qualified name consists of registry name, colon and
metric name, with optional colon and metric property. Colons in names can be escaped using back-slash `\` metric name, with optional colon and metric property. Colons in names can be escaped using back-slash `\`
character. Examples: character. Examples:
`key=solr.node:CONTAINER.fs.totalSpace`
`key=solr.core.collection1:QUERY./select.requestTimes:max_ms` * `key=solr.node:CONTAINER.fs.totalSpace`
`key=solr.jvm:system.properties:user.name` * `key=solr.core.collection1:QUERY./select.requestTimes:max_ms`
* `key=solr.jvm:system.properties:user.name`
compact:: When false, a more verbose format of the response will be returned. Instead of a response like this: compact:: When false, a more verbose format of the response will be returned. Instead of a response like this:
+ +

View File

@ -18,11 +18,11 @@
// specific language governing permissions and limitations // specific language governing permissions and limitations
// under the License. // under the License.
This page explains some of the <<using-jmx-with-solr.adoc#using-jmx-with-solr,JMX>> statistics that Solr exposes. This page explains some of the statistics that Solr exposes.
The same statistics are also exposed via the <<mbean-request-handler.adoc#mbean-request-handler,MBean Request Handler>> when statistics are requested. There are two approaches to retrieving metrics. First, you can use the <<metrics-reporting.adoc#metrics-api,Metrics API>>, or you can enable JMX and get metrics from the <<mbean-request-handler.adoc#mbean-request-handler,MBean Request Handler>> or via an external tool such as JConsole. The below descriptions focus on retrieving the metrics using the Metrics API, but the metric names are the same if using the MBean Request Handler or an external tool.
These statistics are per core. When you are running in SolrCloud mode these statistics would co-relate to each performance of an individual replica. These statistics are per core. When you are running in SolrCloud mode these statistics would co-relate to the performance of an individual replica.
== Request Handler Statistics == Request Handler Statistics
@ -30,67 +30,123 @@ These statistics are per core. When you are running in SolrCloud mode these stat
The update request handler is an endpoint to send data to Solr. We can see how many update requests are being fired, how fast is it performing, and other valuable information regarding requests. The update request handler is an endpoint to send data to Solr. We can see how many update requests are being fired, how fast is it performing, and other valuable information regarding requests.
*Path:* `/solr/<core>/update` *Registry & Path:* `solr.<core>:UPDATE./update`
You can request update request handler statistics with an API request such as `\http://localhost:8983/solr/admin/metrics?group=core&prefix=UPDATE`.
=== Search Request Handler === Search Request Handler
Can be useful to measure and track number of search queries , response times etc. If you are not using the “select” handler then the path needs to be changed appropriately. Similarly if you are using the “sql” handler or “export” handler , the realtime handler “get”, or any other handler similar statistics can be found for that as well. Can be useful to measure and track number of search queries, response times, etc. If you are not using the “select” handler then the path needs to be changed appropriately. Similarly if you are using the “sql” handler or “export” handler , the realtime handler “get”, or any other handler similar statistics can be found for that as well.
*Path*: `/solr/<core>/select` *Registry & Path*: `solr.<core>:QUERY./select`
Both Update Request Handler and Search Request Handler along with handlers like “sql”, “export” and realtime “get” handler will provide the following attributes in their statistics. You can request statistics for the `/select` request handler with an API request such as `\http://localhost:8983/solr/admin/metrics?group=core&prefix=QUERY./select`.
=== Commonly Used Stats for Request Handlers
All of the update and search request handlers will provide the following statistics.
*Request Times*
To get request times, specifically, you can send an API request such as:
* `\http://localhost:8983/solr/admin/metrics?group=core&prefix=UPDATE./update.requestTimes`
* `\http://localhost:8983/solr/admin/metrics?group=core&prefix=QUERY./select.requestTimes`
// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed // TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
[cols="30,70",options="header"] [cols="25,75",options="header"]
|=== |===
|Attribute |Description |Attribute |Description
|15minRateReqsPerSecond |Requests per second received over the past 15 minutes. |15minRate |Requests per second received over the past 15 minutes.
|5minRateReqsPerSecond |Requests per second received over the past 5 minutes. |5minRate |Requests per second received over the past 5 minutes.
|75thPcRequestTime |Request processing time for the request which belongs to the 75th Percentile. E.g., if 100 requests are received, then the 75th fastest request time will be reported by this statistic. |p75_ms |Request processing time for the request which belongs to the 75th Percentile. E.g., if 100 requests are received, then the 75th fastest request time will be reported by this statistic.
|95thPcRequestTime |Request processing time in milliseconds for the request which belongs to the 95th Percentile. E.g., if 80 requests are received, then the 76th fastest request time will be reported in this statistic. |p95_ms |Request processing time in milliseconds for the request which belongs to the 95th Percentile. E.g., if 80 requests are received, then the 76th fastest request time will be reported in this statistic.
|999thPcRequestTime |Request processing time in milliseconds for the request which belongs to the 99.9th Percentile. E.g., if 1000 requests are received, then the 999th fastest request time will be reported in this statistic. |p999_ms |Request processing time in milliseconds for the request which belongs to the 99.9th Percentile. E.g., if 1000 requests are received, then the 999th fastest request time will be reported in this statistic.
|99thPcRequestTime |Request processing time in milliseconds for the request which belongs to the 99th Percentile. E.g., if 200 requests are received, then the 198th fastest request time will be reported in this statistic. |p99_ms |Request processing time in milliseconds for the request which belongs to the 99th Percentile. E.g., if 200 requests are received, then the 198th fastest request time will be reported in this statistic.
|count |Total number of requests made since the Solr process was started.
|median_ms |Median of all the request processing time.
|avgRequestsPerSecond |Average number of requests received per second. |avgRequestsPerSecond |Average number of requests received per second.
|avgTimePerRequest |Average time taken for processing the requests. This parameter will decay over time, with a bias toward activity in the last 5 minutes. |avgTimePerRequest |Average time taken for processing the requests. This parameter will decay over time, with a bias toward activity in the last 5 minutes.
|errors |Number of error encountered by handler. |===
|clientErrors |Number of syntax errors/parse errors made by client while making requests.
|handlerStart |Epoch time when the handler was registered. *Errors and Other Times*
|medianRequestTime |Median of all the request processing time.
|requests |Total number of requests made since the Solr process was started. Other types of data such as errors and timeouts are also provided. These are available under different metric names. For example:
|serverErrors |Number of errors thrown by the server while executing the request.
|timeouts |Number of responses received with partial results. * `\http://localhost:8983/solr/admin/metrics?group=core&prefix=UPDATE./update.errors`
|totalTime |The sum of all request processing times since the Solr process was started. * `\http://localhost:8983/solr/admin/metrics?group=core&prefix=QUERY./select.errors`
The table below shows the metric names and attributes to request:
[cols="25,75",options="header"]
|===
|Metric name | Description
|`QUERY./select.errors`
`UPDATE./update.errors` |Number of errors encountered by handler. In addition to a count of errors, mean, 1 minute, 5 minute, and 15 minute rates are also available.
|`QUERY./select.clientErrors`
`UPDATE./update.clientErrors` |Number of syntax or parse errors made by a client while making requests. In addition to a count of errors, mean, 1 minute, 5 minute, and 15 minute rates are also available.
|`QUERY./select.serverErrors`
`UPDATE./update.serverErrors` |Number of errors thrown by the server while executing the request. In addition to a count of errors, mean, 1 minute, 5 minute, and 15 minute rates are also available.
|`QUERY./select.timeouts`
`UPDATE./update.timeouts` |Number of responses received with partial results. In addition to a count of timeout events, mean, 1 minute, 5 minute, and 15 minute rates are also available.
|`QUERY./select.totalTime`
`UPDATE./update.totalTime` |The sum of all request processing times since the Solr process was started.
|`QUERY./select.handlerStart`
`UPDATE./update.handlerStart` |Epoch time when the handler was registered.
|=== |===
== Update Handler == Update Handler
*Update Handler:* This section has information on the total number of adds, how many commits have been fired against a solr core. This section has information on the total number of adds and how many commits have been fired against a Solr core.
*Registry & Path:* `solr.<core>:UPDATE.updateHandler`
You can get all update handler statistics shown in the table below with an API request such as `\http://localhost:8983/solr/admin/metrics?group=core&prefix=UPDATE.updateHandler`.
The following describes the specific statistics you can get:
*Path:* `/solr/<core>/updateHandler/DirectUpdateHandler2`
// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed // TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
[cols="30,70",options="header"] [cols="40,60",options="header"]
|=== |===
|Attribute |Description |Attribute |Description
|adds |Total number of “add” requests since last commit. |`UPDATE.updateHandler.adds` |Total number of “add” requests since last commit.
|autocommit maxTime |Maximum time between two autocommits execution. |`UPDATE.updateHandler.autoCommitMaxTime` |Maximum time between two auto-commits execution.
|autocommits |Total number of auto-commits executed. |`UPDATE.updateHandler.autoCommits` |Total number of auto-commits executed.
|cumulative_adds |Number of “effective” additions executed over the lifetime. The counter is incremented when “add command is executed while decremented when “rollback” is executed. |`UPDATE.updateHandler.commits` | Number of total commits executed.
|cumulative_deletesById |Number of document deletions executed by ID over the lifetime. The counter is incremented when “delete” command is executed while decremented when “rollback” is executed.
|cumulative_deletesByQuery |Number of document deletions executed by query over the lifetime. The counter is incremented when “delete” command is executed while decremented when “rollback” is executed. In addition to a count of commits, mean, 1 minute, 5 minute, and 15 minute rates are also available.
|cumulative_errors |Number of error messages received by Update Handler while performing addition/deletion action on documents over the lifetime. |`UPDATE.updateHandler.cumulativeAdds` |Number of “effective” additions executed over the lifetime. The counter is incremented when “add command is executed while decremented when “rollback” is executed.
|deletesById |Currently uncommitted deletions by ID.
|deletesByQuery |Currently uncommitted deletions by query. In addition to a count of adds, mean, 1 minute, 5 minute, and 15 minute rates are also available.
|docsPending |Number of documents which are pending commit. |`UPDATE.updateHandler.cumulativeDeletesById` |Number of document deletions executed by ID over the lifetime. The counter is incremented when “delete” command is executed and decremented when “rollback” is executed.
|errors |Number of error messages received by Update Handler while performing addition/deletion/commit/rollback action on documents over the lifetime.
|expungeDeletes |Number of commit commands issued with expunge deletes. In addition to a count of deletes, mean, 1 minute, 5 minute, and 15 minute rates are also available.
|optimizes |Number of explicit optimize commands issued |`UPDATE.updateHandler.cumulativeDeletesByQuery` |Number of document deletions executed by query over the lifetime. The counter is incremented when “delete” command is executed and decremented when “rollback” is executed.
|rollbacks |Number of rollbacks executed.
|soft autocommit maxTime |Maximum documents adds between two soft auto-commits. In addition to a count of deletes, mean, 1 minute, 5 minute, and 15 minute rates are also available.
|soft autocommits |Number of soft commits executed. |`UPDATE.updateHandler.cumulativeErrors` |Number of error messages received while performing addition/deletion actions on documents over the lifetime.
|transaction_logs_total_number |Number of TLogs created from the beginning of the Solr instance. It will be equivalent to number of Hard commits executed.
|transaction_logs_total_size |Total size of all the TLogs created so far from the beginning of the Solr instance. In addition to a count of errors, mean, 1 minute, 5 minute, and 15 minute rates are also available.
|`UPDATE.updateHandler.deletesById` |Currently uncommitted deletions by ID.
|`UPDATE.updateHandler.deletesByQuery` |Currently uncommitted deletions by query.
|`UPDATE.updateHandler.docsPending` |Number of documents which are pending commit.
|`UPDATE.updateHandler.errors` |Number of error messages received while performing addition/deletion/commit/rollback actions on documents over the lifetime of the core.
|`UPDATE.updateHandler.expungeDeletes` |Number of commit commands issued with expunge deletes.
In addition to a count of expunge deletes, mean, 1 minute, 5 minute, and 15 minute rates are also available.
|`UPDATE.updateHandler.merges` | Number of index merges that have occurred.
In addition to a count of merges, mean, 1 minute, 5 minute, and 15 minute rates are also available.
|`UPDATE.updateHandler.optimizes` |Number of explicit optimize commands issued.
In addition to a count of optimizations, mean, 1 minute, 5 minute, and 15 minute rates are also available.
|`UPDATE.updateHandler.rollbacks` |Number of rollbacks executed.
In addition to a count of rollbacks, mean, 1 minute, 5 minute, and 15 minute rates are also available.
|`UPDATE.updateHandler.softAutoCommitMaxTime` |Maximum document adds between two soft auto-commits.
|`UPDATE.updateHandler.softAutoCommits` |Number of soft commits executed.
|=== |===
== Cache Statistics == Cache Statistics
@ -99,23 +155,33 @@ Both Update Request Handler and Search Request Handler along with handlers like
This cache holds Lucene Document objects (the stored fields for each document). Since Lucene internal document IDs are transient, this cache cannot be auto-warmed. This cache holds Lucene Document objects (the stored fields for each document). Since Lucene internal document IDs are transient, this cache cannot be auto-warmed.
*Path:* `/solr/<cache>/documentCache` *Registry and Path:* `solr.<core>:CACHE.searcher.documentCache`
You can get the statistics shown in the table below with an API request such as `\http://localhost:8983/solr/admin/metrics?group=core&prefix=CACHE.searcher.documentCache`.
=== Query Result Cache === Query Result Cache
This cache holds the results of previous searches: ordered lists of document IDs based on a query, a sort, and the range of documents requested This cache holds the results of previous searches: ordered lists of document IDs based on a query, a sort, and the range of documents requested
*Path:* `/solr/<cache>/queryResultCache` *Registry and Path:* `solr.<core>:CACHE.searcher.queryResultCache`
You can get the statistics shown in the table below with an API request such as `\http://localhost:8983/solr/admin/metrics?group=core&prefix=CACHE.searcher.queryResultCache`.
=== Filter Cache === Filter Cache
This cache is used for filters for unordered sets of all documents that match a query. This cache is used for filters for unordered sets of all documents that match a query.
*Path:* `/solr/<cache>/filterCache` *Registry and Path:* `solr.<core>:CACHE.searcher.filterCache`
You can get the statistics shown in the table below with an API request such as `\http://localhost:8983/solr/admin/metrics?group=core&prefix=CACHE.searcher.filterCache`.
=== Statistics for Caches
The following statistics are available for each of the caches mentioned above:
// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed // TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed
[cols="30,70",options="header"] [cols="25,75",options="header"]
|=== |===
|Attribute |Description |Attribute |Description
|cumulative_evictions |Number of cache evictions across all caches since this node has been running. |cumulative_evictions |Number of cache evictions across all caches since this node has been running.

View File

@ -20,71 +20,25 @@
http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html[Java Management Extensions (JMX)] is a technology that makes it possible for complex systems to be controlled by tools without the systems and tools having any previous knowledge of each other. In essence, it is a standard interface by which complex systems can be viewed and manipulated. http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html[Java Management Extensions (JMX)] is a technology that makes it possible for complex systems to be controlled by tools without the systems and tools having any previous knowledge of each other. In essence, it is a standard interface by which complex systems can be viewed and manipulated.
Solr, like any other good citizen of the Java universe, can be controlled via a JMX interface. You can enable JMX support by adding lines to `solrconfig.xml`. You can use a JMX client, like jconsole, to connect with Solr. Check out the Wiki page http://wiki.apache.org/solr/SolrJmx for more information. You may also find the following overview of JMX to be useful: http://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html. Solr, like any other good citizen of the Java universe, can be controlled via a JMX interface. Once enabled, you can use a JMX client, like jconsole, to connect with Solr.
If you are unfamiliar with JMX, you may find the following overview useful: http://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html.
== Configuring JMX == Configuring JMX
JMX configuration is provided in `solrconfig.xml`. Please see the http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html[JMX Technology Home Page] for more details. JMX support is configured by defining a metrics reporter, as described in the section the section <<metrics-reporting.adoc#jmx-reporter,JMX Reporter>>.
A `rootName` attribute can be used when configuring `<jmx />` in `solrconfig.xml`. If this attribute is set, Solr uses it as the root name for all the MBeans that Solr exposes via JMX. The default name is "solr" followed by the core name. If you have an existing MBean server running in Solr's JVM, or if you start Solr with the system property `-Dcom.sun.management.jmxremote`, Solr will automatically identify it's location on startup even if you have not defined a reporter explicitly in `solr.xml`. You can also define the location of the MBean server with parameters defined in the reporter definition.
[IMPORTANT] == Configuring MBean Servers
====
Enabling/disabling JMX and securing access to MBeanServers is left up to the user by specifying appropriate JVM parameters and configuration. Please explore the http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html[JMX Technology Home Page] for more details. Versions of Solr prior to 7.0 defined JMX support in `solrconfig.xml`. This has been changed to the metrics reporter configuration defined above. Parameters for the reporter configuration allow defining the location or address of an existing MBean server.
==== An MBean server can be started at the time of Solr's startup by passing the system parameter `-Dcom.sun.management.jmxremote`. See Oracle's documentation for additional settings available to start and control an MBean server at http://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html.
=== Configuring an Existing MBeanServer
The command:
[source,xml]
----
<jmx />
----
enables JMX support in Solr if and only if an existing MBeanServer is found. Use this if you want to configure JMX with JVM parameters. Remove this to disable exposing Solr configuration and statistics to JMX. If this is specified, Solr will try to list all available MBeanServers and use the first one to register MBeans.
=== Configuring an Existing MBeanServer with agentId
The command:
[source,xml]
----
<jmx agentId="myMBeanServer" />
----
enables JMX support in Solr if and only if an existing MBeanServer is found matching the given agentId. If multiple servers are found, the first one is used. If none is found, an exception is raised and depending on the configuration, Solr may refuse to start.
=== Configuring a New MBeanServer
The command:
[source,xml]
----
<jmx serviceUrl="service:jmx:rmi:///jndi/rmi://localhost:9999/solrjmx" />
----
creates a new MBeanServer exposed for remote monitoring at the specific service URL. If the JMXConnectorServer can't be started (probably because the serviceUrl is bad), an exception is thrown.
==== MBean Server Example
Solr's `sample_techproducts_configs` config set uses the simple `<jmx />` configuration option. If you start the example with the necessary JVM system properties to launch an internal MBeanServer, Solr will register with it and you can connect using a tool like `jconsole`:
1. Launch the `techproducts` example with JMX enabled:
+
[source,bash]
----
bin/solr -e techproducts -Dcom.sun.management.jmxremote
----
2. Start `jconsole` (provided with the Sun JDK in the bin directory).
3. Connect to the "`start.jar`" shown in the list of local processes.
4. Switch to the "MBeans" tab. You should be able to see "`solr/techproducts`" listed there, at which point you can drill down and see details of every solr plugin.
=== Configuring a Remote Connection to Solr JMX === Configuring a Remote Connection to Solr JMX
If you need to attach a JMX-enabled Java profiling tool, such as JConsole or VisualVM, to a remote Solr server, then you need to enable remote JMX access when starting the Solr server. Simply change the `ENABLE_REMOTE_JMX_OPTS` property in the include file to true. Youll also need to choose a port for the JMX RMI connector to bind to, such as 18983. For example, if your Solr include script sets: If you need to attach a JMX-enabled Java profiling tool, such as JConsole or VisualVM, to a remote Solr server, then you need to enable remote JMX access when starting the Solr server. Simply change the `ENABLE_REMOTE_JMX_OPTS` property in the `solr.in.sh` or `solr.in.cmd` (for Windows) file to true. Youll also need to choose a port for the JMX RMI connector to bind to, such as 18983. For example, if your Solr include script sets:
[source,bash] [source,bash]
---- ----
@ -106,11 +60,9 @@ The JMX RMI connector will allow Java profiling tools to attach to port 18983. W
We dont recommend enabling remote JMX access in production, but it can sometimes be useful when doing performance and user-acceptance testing prior to going into production. We dont recommend enabling remote JMX access in production, but it can sometimes be useful when doing performance and user-acceptance testing prior to going into production.
For more information about these settings, see: For more information about these settings, see: http://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html.
http://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html
[IMPORTANT] [IMPORTANT]
==== ====
Making JMX connections into machines running behind NATs (e.g. Amazon's EC2 service) is not a simple task. The `java.rmi.server.hostname` system property may help, but running `jconsole` on the server itself and using a remote desktop is often the simplest solution. See http://web.archive.org/web/20130525022506/http://jmsbrdy.com/monitoring-java-applications-running-on-ec2-i. Making JMX connections into machines running behind NATs (e.g., Amazon's EC2 service) is not a simple task. The `java.rmi.server.hostname` system property may help, but running `jconsole` on the server itself and using a remote desktop is often the simplest solution. See http://web.archive.org/web/20130525022506/http://jmsbrdy.com/monitoring-java-applications-running-on-ec2-i.
==== ====