| // Licensed to the Apache Software Foundation (ASF) under one or more |
| // contributor license agreements. See the NOTICE file distributed with |
| // this work for additional information regarding copyright ownership. |
| // The ASF licenses this file to You under the Apache License, Version 2.0 |
| // (the "License"); you may not use this file except in compliance with |
| // the License. You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| = New Metrics System |
| |
| :javaFile: {javaCodeDir}/ConfiguringMetrics.java |
| |
| == Overview |
| |
| WARNING: Experimental |
| |
| Ignite 2.8 introduced a new mechanism for collecting metrics, which is intended to replace the link:monitoring-metrics/metrics[legacy metrics system]. |
| This section explains the new system and how you can use it to monitor your cluster. |
| //the types of metrics and how to export them, but first let's explore the basic concepts of the new metrics mechanism in Ignite. |
| |
| Let's explore the basic concepts of the new metrics system in Ignite. |
| First, there are different metrics. |
| Each metric has a name and a return value. |
| The return value can be a simple value like `String`, `long`, or `double`, or can represent a Java object. |
| Some metrics represent <<histograms>>. |
| |
| And then there are different ways to export the metrics — what we call _exporters_. |
| To put it another way, the exporter are different ways you can access the metrics. |
| Each exporter always gives access to all available metrics. |
| |
| Ignite includes the following exporters: |
| |
| * JMX |
| * SQL Views |
| * Log files |
| * OpenCensus |
| |
| You can create a custom exporter by implementing the javadoc:org.apache.ignite.spi.metric.MetricExporterSpi[] interface. |
| |
| |
| == Metric Registers |
| |
| Metrics are grouped into categories (called _registers_). |
| Each register has a name. |
| The full name of a specific metric within the register consists of the register name followed by a dot, followed by the name of the metric: `<register_name>.<metric_name>`. |
| For example, the register for data storage metrics is called `io.datastorage`. |
| The metric that return the storage size is called `io.datastorage.StorageSize`. |
| |
| The list of all registers and the metrics they contain are described link:monitoring-metrics/new-metrics[here]. |
| |
| == Metric Exporters |
| |
| If you want to enable metrics, configure one or multiple metric exporters in the node configuration. |
| This is a node-specific configuration, which means it enables metrics only on the node where it is specified. |
| |
| [tabs] |
| -- |
| tab:XML[] |
| [source, xml] |
| ---- |
| include::code-snippets/xml/metrics.xml[tags=ignite-config;!discovery, indent=0] |
| ---- |
| |
| tab:Java[] |
| |
| [source, java] |
| ---- |
| include::{javaFile}[tags=new-metric-framework, indent=0] |
| ---- |
| |
| tab:C#/.NET[] |
| |
| tab:C++[unsupported] |
| -- |
| |
| The following sections describe the exporters available in Ignite by default. |
| |
| |
| === JMX |
| |
| `org.apache.ignite.spi.metric.jmx.JmxMetricExporterSpi` exposes metrics via JMX beans. |
| |
| [tabs] |
| -- |
| tab:Java[] |
| [source, java] |
| ---- |
| include::{javaFile}[tags=metrics-filter, indent=0] |
| ---- |
| |
| tab:C#/.NET[] |
| |
| tab:C++[unsupported] |
| -- |
| |
| |
| === SQL View |
| |
| `org.apache.ignite.spi.metric.sql.SqlViewMetricExporterSpi` exposes metrics via the `SYS.METRICS` view. |
| Each metric is displayed as a single record. |
| You can use any supported SQL tool to view the metrics: |
| |
| [source, shell,subs="attributes"] |
| ---- |
| > select name, value from SYS.METRICS where name LIKE 'cache.myCache.%'; |
| +-----------------------------------+--------------------------------+ |
| | NAME | VALUE | |
| +-----------------------------------+--------------------------------+ |
| | cache.myCache.CacheTxRollbacks | 0 | |
| | cache.myCache.OffHeapRemovals | 0 | |
| | cache.myCache.QueryCompleted | 0 | |
| | cache.myCache.QueryFailed | 0 | |
| | cache.myCache.EstimatedRebalancingKeys | 0 | |
| | cache.myCache.CacheEvictions | 0 | |
| | cache.myCache.CommitTime | [J@2eb66498 | |
| .... |
| ---- |
| |
| This is how you can configure the SQL View exporter: |
| |
| [tabs] |
| -- |
| tab:XML[] |
| [source, xml] |
| ---- |
| include::code-snippets/xml/metrics.xml[tags=!*;ignite-config;sql-exporter, indent=0] |
| ---- |
| |
| tab:Java[] |
| |
| [source, java] |
| ---- |
| include::{javaFile}[tags=sql-exporter, indent=0] |
| ---- |
| |
| tab:C#/.NET[] |
| |
| tab:C++[unsupported] |
| -- |
| |
| === Log |
| |
| `org.apache.ignite.spi.metric.log.LogExporterSpi` prints the metrics to the log file at regular intervals (1 min by default) at INFO level. |
| |
| [tabs] |
| -- |
| tab:XML[] |
| |
| [source, xml] |
| ---- |
| include::code-snippets/xml/metrics.xml[tags=!*;ignite-config;log-exporter, indent=0] |
| ---- |
| |
| |
| tab:Java[] |
| |
| If you use programmatic configuration, you can change the print frequency as follows: |
| |
| [source, java] |
| ---- |
| include::{javaFile}[tags=log-exporter, indent=0] |
| ---- |
| |
| tab:C#/.NET[] |
| tab:C++[] |
| -- |
| |
| === OpenCensus |
| |
| `org.apache.ignite.spi.metric.opencensus.OpenCensusMetricExporterSpi` adds integration with the OpenCensus library. |
| |
| To use the OpenCensus exporter: |
| |
| . link:setup#enabling-modules[Enable the 'ignite-opencensus' module]. |
| . Add `org.apache.ignite.spi.metric.opencensus.OpenCensusMetricExporterSpi` to the list of exporters in the node configuration. |
| . Configure OpenCensus StatsCollector to export to a specific system. See link:{githubUrl}/examples/src/main/java/org/apache/ignite/examples/opencensus/OpenCensusMetricsExporterExample.java[OpenCensusMetricsExporterExample.java] for an example and OpenCensus documentation for additional information. |
| |
| |
| Configuration parameters: |
| |
| * `filter` - predicate that filters metrics. |
| * `period` - export period. |
| * `sendInstanceName` - if enabled, a tag with the Ignite instance name is added to each metric. |
| * `sendNodeId` - if enabled, a tag with the Ignite node id is added to each metric. |
| * `sendConsistentId` - if enabled, a tag with the Ignite node consistent id is added to each metric. |
| |
| |
| |
| |
| == Histograms |
| |
| The metrics that represent histograms are available in the JMX exporter only. |
| Histogram metrics are exported as a set of values where each value corresponds to a specific bucket and is available through a separate JMX bean attribute. |
| The attribute names of a histogram metric have the following format: |
| |
| ``` |
| {metric_name}_{low_bound}_{high_bound} |
| ``` |
| |
| where |
| |
| * `{metric_name}` - the name of the metric. |
| * `{low_bound}` - start of the bound. `0` for the first bound. |
| * `{high_bound}` - end of the bound. `inf` for the last bound. |
| |
| |
| Example of the metric names if the bounds are [10,100]: |
| |
| * `histogram_0_10` - less than 10. |
| * `histogram_10_100` - between 10 and 100. |
| * `histogram_100_inf` - more than 100. |
| |
| |
| |