|
1 | | -# System Metrics<img align="right" src="https://rawgit.com/kamon-io/Kamon/master/kamon-logo.svg" height="150px" style="padding-left: 20px"/> |
| 1 | +# This reporsitory has been moved. |
2 | 2 |
|
3 | | - |
4 | | - |
5 | | -[](https://gitter.im/kamon-io/Kamon?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) |
6 | | -[](https://maven-badges.herokuapp.com/maven-central/io.kamon/kamon-system-metrics_2.12) |
7 | | - |
8 | | -Our `kamon-system-metrics` module registers a number of entities with the metrics module that track the performance |
9 | | -indicators of both the host machine and the JVM where your application is running. |
10 | | - |
11 | | -This module doesn't have any bytecode instrumentation requirement, and its only requirement to work properly is that |
12 | | -the appropriate [Sigar] native library is correctly loaded. To do so, the `kamon-system-metrics` module makes use of the |
13 | | -[sigar-loader] library. If your application uses Sigar for other purposes, it is advisable that you take a look at |
14 | | -[sigar-loader] to simplify the sigar native library provisioning process. |
15 | | - |
16 | | - |
17 | | -### Getting Started |
18 | | - |
19 | | -Kamon sytem-metrics module is currently available for Scala 2.10, 2.11 and 2.12. |
20 | | - |
21 | | -Supported releases and dependencies are shown below. |
22 | | - |
23 | | -| kamon-system-metrics | status | jdk | scala |
24 | | -|:------:|:------:|:----:|------------------| |
25 | | -| 1.0.1 | stable |1.8+ | 2.10, 2.11, 2.12 |
26 | | - |
27 | | -To get started with SBT, simply add the following to your `build.sbt` or `pom.xml` |
28 | | -file: |
29 | | - |
30 | | -```scala |
31 | | -libraryDependencies += "io.kamon" %% "kamon-system-metrics" % "1.0.0" |
32 | | -``` |
33 | | -```xml |
34 | | -<dependency> |
35 | | - <groupId>io.kamon</groupId> |
36 | | - <artifactId>kamon-system-metrics_2.12</artifactId> |
37 | | - <version>1.0.1</version> |
38 | | -</dependency> |
39 | | -``` |
40 | | - |
41 | | -##### Start |
42 | | -```scala |
43 | | -SystemMetrics.startCollecting() |
44 | | -``` |
45 | | -##### Stop |
46 | | -```scala |
47 | | -SystemMetrics.stopCollecting() |
48 | | -``` |
49 | | - |
50 | | - |
51 | | -As you might expect, you and any other module can subscribe to all the metrics that are reported by this module using |
52 | | -the `system-metric` category and the entity recorder names described bellow. |
53 | | - |
54 | | -By default the `kamon-system-metrics` module starts with Host and JVM metrics enabled, in the case that you want to **enable/disable** one of them, you can configure it this way: |
55 | | - |
56 | | -```typesafeconfig |
57 | | -kamon { |
58 | | - system-metrics { |
59 | | - # sigar is enabled by default |
60 | | - host.enabled = true |
61 | | -
|
62 | | - # jmx related metrics are enabled by default |
63 | | - jmx.enabled = true |
64 | | - } |
65 | | -} |
66 | | -``` |
67 | | -Host System Metrics |
68 | | -------------------- |
69 | | - |
70 | | -We are using [Sigar] to gather all the host system metrics information and this requires us to have a few special |
71 | | -considerations given that [Sigar] instances are not thread-safe and some metrics (like cpu usage metrics) do not work |
72 | | -correctly when updated in intervals of less than a second. In the sections below, you will see histograms tracking |
73 | | -metrics that typically should be recorded with a gauge, but that we couldn't allow because of the need to have a tight |
74 | | -control on timings and thread-safety. |
75 | | - |
76 | | -In the case that <b>Sigar</b> can't obtain some metric in the host, we will log a warning indicating the error and the metric name. |
77 | | - |
78 | | -### cpu ### |
79 | | -* __user__: a histogram tracking total percentage of system cpu user time. |
80 | | -* __system__: a histogram tracking total percentage of system cpu kernel time. |
81 | | -* __wait__: a histogram tracking total percentage of system cpu io wait time. |
82 | | -* __idle__: a histogram tracking total percentage of system cpu idle time |
83 | | -* __stolen__: a histogram tracking total percentage of system cpu involuntary wait time. |
84 | | - |
85 | | - |
86 | | -### file-system ### |
87 | | -* __readBytes__: a histogram tracking total number of physical disk reads in bytes. |
88 | | -* __writesBytes__: a histogram tracking total number of physical disk writes in bytes. |
89 | | - |
90 | | - |
91 | | -### load-average ### |
92 | | -* __one-minute__: a histogram tracking the system load average for the last minute. |
93 | | -* __five-minutes__: a histogram tracking the system load average for the five minutes. |
94 | | -* __fifteen-minutes__: a histogram tracking the system load average for the fifteen minutes. |
95 | | - |
96 | | - |
97 | | -### memory ### |
98 | | -* __memory-used__: a histogram tracking total used system memory in bytes. |
99 | | -* __memory-cache-and-buffer__: a histogram tracking total memory used in cache and buffers memory in bytes. |
100 | | -* __memory-free__: a histogram tracking total free system memory in bytes. |
101 | | -* __memory-total__: a histogram tracking total system memory capacity in bytes. |
102 | | -* __swap-used__: a histogram tracking total used system swap in bytes. |
103 | | -* __swap-free__: a histogram tracking total used system swap in bytes. |
104 | | - |
105 | | - |
106 | | -### network ### |
107 | | - |
108 | | -All network metrics represent the aggregate of all interfaces available in the host. |
109 | | - |
110 | | -* __rx-bytes__: a histogram tracking total number of received packets in bytes. |
111 | | -* __tx-bytes__: a histogram tracking total number of transmitted packets in bytes. |
112 | | -* __rx-errors__: a histogram tracking total number of packets received with errors. This includes too-long-frames errors, ring-buffer overflow errors, etc. |
113 | | -* __tx-errors__: a histogram tracking total number of errors encountered while transmitting packets. This list includes errors due to the transmission being aborted, errors due to the carrier, etc. |
114 | | -* __rx-dropped__: a histogram tracking total number of incoming packets dropped. |
115 | | -* __tx-dropped__: a histogram tracking total number of outgoing packets dropped. |
116 | | - |
117 | | - |
118 | | -### process-cpu ### |
119 | | -* __process-user-cpu__: a histogram tracking the total percentage of CPU spent by the application process in user space, relative to the overall CPU usage. |
120 | | -* __process-system-cpu__: a histogram tracking the total percentage of CPU spent by the application process in system space, relative to the overall CPU usage. |
121 | | -* __process-cpu__: a histogram tracking the total percentage of CPU spent by the application, relative to the overall CPU usage. |
122 | | - |
123 | | - |
124 | | -### context-switches ### |
125 | | - |
126 | | -The context switches metrics are special in the sense that they are not read using the [Sigar] library but rather reading |
127 | | -the information available in the `/proc/$pid/status` file for Linux systems. |
128 | | - |
129 | | -* __context-switches-process-voluntary__: Total number of voluntary context switches related to the current process (one |
130 | | -thread explicitly yield the CPU to another). |
131 | | -* __context-switches-process-non-voluntary__: Total number of involuntary context switches related to the current process |
132 | | -(the system scheduler suspends an active thread, and switches control to a different thread). |
133 | | -* __context-switches-global__: Total number of context switches across all CPUs. |
134 | | - |
135 | | -JVM Metrics |
136 | | ------------ |
137 | | - |
138 | | -All JVM-specific metrics are gathered using JMX and all of them are using gauges to record the data. The reported JVM |
139 | | -metrics include: |
140 | | - |
141 | | - |
142 | | -### \*-garbage-collector ### |
143 | | - |
144 | | -Depending on your specific instance configuration, the available garbage collectors will differ, but the same set of |
145 | | -metrics are recorded regardless of the collector in place. |
146 | | - |
147 | | -* __garbage-collection-count__: a gauge tracking the number of garbage collections that have ocurred. |
148 | | -* __garbage-collection-time__: a gauge tracking the time spent in garbage collections, measured in milliseconds. |
149 | | - |
150 | | - |
151 | | -### class-loading ### |
152 | | -* __classes-loaded__: a gauge tracking the number of classes ever loaded by the application. |
153 | | -* __classes-unloaded__: a gauge tracking the number of classes ever unloaded by the application. |
154 | | -* __classes-currently-loaded__: a gauge tracking the number of classes currently loaded by the application. |
155 | | - |
156 | | - |
157 | | -### heap-memory ### |
158 | | -* __heap-used__: a gauge tracking the amount of heap memory currently being used in bytes. |
159 | | -* __heap-max__: a gauge tracking the maximum amount of heap memory that can be used in bytes. |
160 | | -* __heap-committed__: a gauge tracking the amount of memory that is committed for the JVM to use in bytes. |
161 | | - |
162 | | - |
163 | | -### non-heap-memory ### |
164 | | -* __non-heap-used__: a gauge tracking the amount of non-heap memory currently being used in bytes. |
165 | | -* __non-heap-max__: a gauge tracking the maximum amount of non-heap memory that can be used in bytes. |
166 | | -* __non-heap-committed__: a gauge tracking the amount of non-heap memory that is committed for the JVM to use in bytes. |
167 | | - |
168 | | - |
169 | | -### threads ### |
170 | | -* __daemon-thread-count__: a gauge tracking the total number of daemon threads running in the JVM. |
171 | | -* __peak-thread-count__: a gauge tracking the peak number of threads running in the JVM since it started. |
172 | | -* __thread-count__: a gauge tracking the total number of live threads in the JVM, including both daemon and non-daemon threads. |
173 | | - |
174 | | - |
175 | | -[Sigar]: https://github.com/hyperic/sigar |
176 | | -[sigar-loader]: https://github.com/kamon-io/sigar-loader |
| 3 | +Since March 2020 all the Kamon instrumentation and reporting modules were moved to Kamon's main repository at [https://github.com/kamon-io/kamon](https://github.com/kamon-io/kamon). Please check out the main repository for the latest sources, reporting issues or start contributing. You can also stop by our [Gitter Channel](https://gitter.im/kamon-io/Kamon). |
0 commit comments