tsd_metrics 0.2.0 → 0.2.8
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +15 -0
- data/.gitignore +23 -0
- data/.travis.yml +13 -0
- data/CONTRIBUTORS.md +10 -0
- data/DEPENDENCIES.md +15 -0
- data/Gemfile +22 -0
- data/LICENSE +158 -0
- data/README.md +182 -0
- data/Rakefile +5 -0
- data/demo.rb +27 -0
- data/doc/QUERY_LOG_FORMAT.md +59 -0
- data/doc/query-log-schema-2c.json +55 -0
- data/doc/query-log-schema-2d.json +69 -0
- data/doc/query-log-schema-2e.json +103 -0
- data/lib/tsd_metrics/async_queue_writer.rb +40 -0
- data/lib/tsd_metrics/counter.rb +43 -0
- data/lib/tsd_metrics/counter_sample.rb +37 -0
- data/lib/tsd_metrics/exceptions.rb +22 -0
- data/lib/tsd_metrics/json_formatting_sink.rb +63 -0
- data/lib/tsd_metrics/metric_builder_for_single_struct_receiver.rb +24 -0
- data/lib/tsd_metrics/queue_writer.rb +24 -0
- data/lib/tsd_metrics/timer.rb +48 -0
- data/lib/tsd_metrics/timer_sample.rb +69 -0
- data/lib/tsd_metrics/tsd_metric.rb +200 -0
- data/lib/tsd_metrics/units.rb +22 -0
- data/lib/tsd_metrics.rb +63 -15
- data/resources/LICENSE +158 -0
- data/spec/integration_spec.rb +84 -0
- data/spec/json_formatter_spec.rb +99 -0
- data/spec/tsd_metric_spec.rb +289 -0
- data/spec/tsd_metrics_spec.rb +22 -0
- data/spec/units_utils_spec.rb +29 -0
- data/tsd_metrics.gemspec +35 -0
- metadata +124 -82
checksums.yaml
ADDED
@@ -0,0 +1,15 @@
|
|
1
|
+
---
|
2
|
+
!binary "U0hBMQ==":
|
3
|
+
metadata.gz: !binary |-
|
4
|
+
MmE1MmVlZTkwYWQyODhkYWJkY2RmNjVmNjRjMjFmZDFhZDY2MTE2Mw==
|
5
|
+
data.tar.gz: !binary |-
|
6
|
+
NGE0YTZjM2YwZGZiZjg5ZTMxYTQ1MmQ1NjkzZTdiMzE4NmM4OWQ5Zg==
|
7
|
+
SHA512:
|
8
|
+
metadata.gz: !binary |-
|
9
|
+
MTQ2MDQ1MjU2ZjdmZGNlMzgwODU5NGFjMDE5NTlkZDZlNjY3MDZiNjk3MjNk
|
10
|
+
MTRjNzJjZGQ5NmUyN2E2NThhZGJkZDVjNGU4ODhlOTQ2NThhZDllYWJiNzZm
|
11
|
+
NGJlYTc2MDE1ZWExOTk0MzdlZjI4MzNiZTNlNWU2MTEyYTcwMjc=
|
12
|
+
data.tar.gz: !binary |-
|
13
|
+
ZDIyNWI4YzM3NWIyZWYzZWQ2NzdkNTBlMTMzM2RiYzNlY2UxNjg2ZDcxZWE1
|
14
|
+
MDhkOGMzMzExNzJlNjgwNWRlZTRiNDk5NzBjZTAyMmRjZjk2MTE1OTliNWNh
|
15
|
+
M2NkYzhlY2YxMDBiN2NlNGIwNjViYmY2ZTY0MDNlZmEyZDA4N2Q=
|
data/.gitignore
ADDED
@@ -0,0 +1,23 @@
|
|
1
|
+
# Output
|
2
|
+
*.gem
|
3
|
+
.bundle
|
4
|
+
.rakeTasks
|
5
|
+
tmp
|
6
|
+
.gemencap
|
7
|
+
my_file.json
|
8
|
+
|
9
|
+
# Eclipse
|
10
|
+
.metadata/
|
11
|
+
.externalToolBuilders/
|
12
|
+
bin/
|
13
|
+
eclipse-bin/
|
14
|
+
**/.classpath
|
15
|
+
**/RemoteSystemsTempFiles/
|
16
|
+
|
17
|
+
# IntelliJ
|
18
|
+
.idea
|
19
|
+
.settings/
|
20
|
+
*.iml
|
21
|
+
|
22
|
+
# Mac
|
23
|
+
.DS_Store
|
data/.travis.yml
ADDED
@@ -0,0 +1,13 @@
|
|
1
|
+
language: ruby
|
2
|
+
rvm:
|
3
|
+
- 1.9.3
|
4
|
+
- 2.0.0
|
5
|
+
- 2.1.0
|
6
|
+
deploy:
|
7
|
+
provider: rubygems
|
8
|
+
gem: tsd_metrics
|
9
|
+
on:
|
10
|
+
tags: true
|
11
|
+
rvm: 1.9.3
|
12
|
+
api_key:
|
13
|
+
secure: KACQT1NXqlICT2qSVobhBGRi71nw6JCuWUZZN59KeMfIqQhGwSnNJ8JpXVhrrz7lijAWbNAeW0aimf8toeeaRQiaP468o0eAH8WkWzOImFaSLs8TEiH4cZEt/QxBV3RP6BWJJkPK+VjLY3w2x4DzKQbpkJvTmIkLg+M4wgG4hmoDlEcEQ5NHrNv45BjxzaA6n/Wh1vLcsZy0PgXR4RgDeLnpzu/2/OqKeLecyrQvHh7IrJUvlgVBOAliZE8cEps5ebRqNrrLXWfKHLPzmyx/alRZFwllPveb5Gx3WymYamiiJOComfLPxg58v/fI7sKrkqWYgpgXPd41fwEh6yuK2D7siG8QC+sUZxLjwzJjm/xU7C64pjCUzbONx9Ju0849f8mfl7d4JSeEtKd6dxGdtotE/mlQIdnFac60T5dQ0BBfcSBa3+yegpvuvtsgKzZpa7ceSM9nBRMqTXoGwN+mhEKxTYJo4iWW5lLqSvUU5a9Ho0Prf+aMT5ntc01ax/U1cgV7jK3bwmRzsmEfRl1nW6Q1DJmjloZY0jgNJnaOhfZ0Yj9CE1gNPzGCI2yDIq+fHQ3EluSJGKpXmSao5eR2PYNvmel/S93/v4lxgMKxx1veewM9l8OjEjelQcKFrnH1efHzP8UOsv4LScbQgKJTH7SgmXWvvrKQBEN+zDztt1Q=
|
data/CONTRIBUTORS.md
ADDED
@@ -0,0 +1,10 @@
|
|
1
|
+
Contributors
|
2
|
+
============
|
3
|
+
|
4
|
+
The following people have made source contributions to the metrics client ruby project:
|
5
|
+
|
6
|
+
* Brandon Arp (barp at groupon dot com)
|
7
|
+
* Matthew Hayter (mhayter at groupon dot com)
|
8
|
+
* Ville Koskela (vkoskela at groupon dot com)
|
9
|
+
|
10
|
+
© Groupon Inc., 2014
|
data/DEPENDENCIES.md
ADDED
@@ -0,0 +1,15 @@
|
|
1
|
+
Dependencies
|
2
|
+
========
|
3
|
+
|
4
|
+
The following table lists the dependencies of the ruby client and their licenses.
|
5
|
+
|
6
|
+
Build Tool Dependencies
|
7
|
+
------------------
|
8
|
+
|
9
|
+
Project | License | Project link
|
10
|
+
---------------------|----------------------------|-------------
|
11
|
+
rspec | MIT | https://github.com/rspec/rspec
|
12
|
+
timecop | MIT | https://github.com/travisjeffery/timecop
|
13
|
+
pry | MIT | https://github.com/pry/pry
|
14
|
+
|
15
|
+
© Groupon Inc., 2014
|
data/Gemfile
ADDED
@@ -0,0 +1,22 @@
|
|
1
|
+
# Copyright 2014 Groupon.com
|
2
|
+
#
|
3
|
+
# Licensed under the Apache License, Version 2.0 (the "License");
|
4
|
+
# you may not use this file except in compliance with the License.
|
5
|
+
# You may obtain a copy of the License at
|
6
|
+
#
|
7
|
+
# http://www.apache.org/licenses/LICENSE-2.0
|
8
|
+
#
|
9
|
+
# Unless required by applicable law or agreed to in writing, software
|
10
|
+
# distributed under the License is distributed on an "AS IS" BASIS,
|
11
|
+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
12
|
+
# See the License for the specific language governing permissions and
|
13
|
+
# limitations under the License.
|
14
|
+
|
15
|
+
# A sample Gemfile
|
16
|
+
source "https://rubygems.org"
|
17
|
+
|
18
|
+
gemspec
|
19
|
+
|
20
|
+
group :test do
|
21
|
+
gem 'rake'
|
22
|
+
end
|
data/LICENSE
ADDED
@@ -0,0 +1,158 @@
|
|
1
|
+
Apache License
|
2
|
+
|
3
|
+
Version 2.0, January 2004
|
4
|
+
|
5
|
+
http://www.apache.org/licenses/
|
6
|
+
|
7
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
8
|
+
|
9
|
+
1. Definitions.
|
10
|
+
|
11
|
+
"License" shall mean the terms and conditions for use, reproduction, and
|
12
|
+
distribution as defined by Sections 1 through 9 of this document.
|
13
|
+
|
14
|
+
"Licensor" shall mean the copyright owner or entity authorized by the copyright
|
15
|
+
owner that is granting the License.
|
16
|
+
|
17
|
+
"Legal Entity" shall mean the union of the acting entity and all other entities
|
18
|
+
that control, are controlled by, or are under common control with that entity.
|
19
|
+
For the purposes of this definition, "control" means (i) the power, direct or
|
20
|
+
indirect, to cause the direction or management of such entity, whether by
|
21
|
+
contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
22
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
23
|
+
|
24
|
+
"You" (or "Your") shall mean an individual or Legal Entity exercising
|
25
|
+
permissions granted by this License.
|
26
|
+
|
27
|
+
"Source" form shall mean the preferred form for making modifications, including
|
28
|
+
but not limited to software source code, documentation source, and configuration
|
29
|
+
files.
|
30
|
+
|
31
|
+
"Object" form shall mean any form resulting from mechanical transformation or
|
32
|
+
translation of a Source form, including but not limited to compiled object code,
|
33
|
+
generated documentation, and conversions to other media types.
|
34
|
+
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or Object form, made
|
36
|
+
available under the License, as indicated by a copyright notice that is included
|
37
|
+
in or attached to the work (an example is provided in the Appendix below).
|
38
|
+
|
39
|
+
"Derivative Works" shall mean any work, whether in Source or Object form, that
|
40
|
+
is based on (or derived from) the Work and for which the editorial revisions,
|
41
|
+
annotations, elaborations, or other modifications represent, as a whole, an
|
42
|
+
original work of authorship. For the purposes of this License, Derivative Works
|
43
|
+
shall not include works that remain separable from, or merely link (or bind by
|
44
|
+
name) to the interfaces of, the Work and Derivative Works thereof.
|
45
|
+
|
46
|
+
"Contribution" shall mean any work of authorship, including the original version
|
47
|
+
of the Work and any modifications or additions to that Work or Derivative Works
|
48
|
+
thereof, that is intentionally submitted to Licensor for inclusion in the Work
|
49
|
+
by the copyright owner or by an individual or Legal Entity authorized to submit
|
50
|
+
on behalf of the copyright owner. For the purposes of this definition,
|
51
|
+
"submitted" means any form of electronic, verbal, or written communication sent
|
52
|
+
to the Licensor or its representatives, including but not limited to
|
53
|
+
communication on electronic mailing lists, source code control systems, and
|
54
|
+
issue tracking systems that are managed by, or on behalf of, the Licensor for
|
55
|
+
the purpose of discussing and improving the Work, but excluding communication
|
56
|
+
that is conspicuously marked or otherwise designated in writing by the copyright
|
57
|
+
owner as "Not a Contribution."
|
58
|
+
|
59
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
|
60
|
+
of whom a Contribution has been received by Licensor and subsequently
|
61
|
+
incorporated within the Work.
|
62
|
+
|
63
|
+
2. Grant of Copyright License. Subject to the terms and conditions of this
|
64
|
+
License, each Contributor hereby grants to You a perpetual, worldwide,
|
65
|
+
non-exclusive, no-charge, royalty-free, irrevocable copyright license to
|
66
|
+
reproduce, prepare Derivative Works of, publicly display, publicly perform,
|
67
|
+
sublicense, and distribute the Work and such Derivative Works in Source or
|
68
|
+
Object form.
|
69
|
+
|
70
|
+
3. Grant of Patent License. Subject to the terms and conditions of this License,
|
71
|
+
each Contributor hereby grants to You a perpetual, worldwide, non-exclusive,
|
72
|
+
no-charge, royalty-free, irrevocable (except as stated in this section) patent
|
73
|
+
license to make, have made, use, offer to sell, sell, import, and otherwise
|
74
|
+
transfer the Work, where such license applies only to those patent claims
|
75
|
+
licensable by such Contributor that are necessarily infringed by their
|
76
|
+
Contribution(s) alone or by combination of their Contribution(s) with the Work
|
77
|
+
to which such Contribution(s) was submitted. If You institute patent litigation
|
78
|
+
against any entity (including a cross-claim or counterclaim in a lawsuit)
|
79
|
+
alleging that the Work or a Contribution incorporated within the Work
|
80
|
+
constitutes direct or contributory patent infringement, then any patent licenses
|
81
|
+
granted to You under this License for that Work shall terminate as of the date
|
82
|
+
such litigation is filed.
|
83
|
+
|
84
|
+
4. Redistribution. You may reproduce and distribute copies of the Work or
|
85
|
+
Derivative Works thereof in any medium, with or without modifications, and in
|
86
|
+
Source or Object form, provided that You meet the following conditions:
|
87
|
+
|
88
|
+
a. You must give any other recipients of the Work or Derivative Works a copy of
|
89
|
+
this License; and
|
90
|
+
b. You must cause any modified files to carry prominent notices stating that You
|
91
|
+
changed the files; and
|
92
|
+
c. You must retain, in the Source form of any Derivative Works that You
|
93
|
+
distribute, all copyright, patent, trademark, and attribution notices from the
|
94
|
+
Source form of the Work, excluding those notices that do not pertain to any part
|
95
|
+
of the Derivative Works; and
|
96
|
+
d. If the Work includes a "NOTICE" text file as part of its distribution, then
|
97
|
+
any Derivative Works that You distribute must include a readable copy of the
|
98
|
+
attribution notices contained within such NOTICE file, excluding those notices
|
99
|
+
that do not pertain to any part of the Derivative Works, in at least one of the
|
100
|
+
following places: within a NOTICE text file distributed as part of the
|
101
|
+
Derivative Works; within the Source form or documentation, if provided along
|
102
|
+
with the Derivative Works; or, within a display generated by the Derivative
|
103
|
+
Works, if and wherever such third-party notices normally appear. The contents of
|
104
|
+
the NOTICE file are for informational purposes only and do not modify the
|
105
|
+
License. You may add Your own attribution notices within Derivative Works that
|
106
|
+
You distribute, alongside or as an addendum to the NOTICE text from the Work,
|
107
|
+
provided that such additional attribution notices cannot be construed as
|
108
|
+
modifying the License.
|
109
|
+
|
110
|
+
You may add Your own copyright statement to Your modifications and may provide
|
111
|
+
additional or different license terms and conditions for use, reproduction, or
|
112
|
+
distribution of Your modifications, or for any such Derivative Works as a whole,
|
113
|
+
provided Your use, reproduction, and distribution of the Work otherwise complies
|
114
|
+
with the conditions stated in this License.
|
115
|
+
|
116
|
+
5. Submission of Contributions. Unless You explicitly state otherwise, any
|
117
|
+
Contribution intentionally submitted for inclusion in the Work by You to the
|
118
|
+
Licensor shall be under the terms and conditions of this License, without any
|
119
|
+
additional terms or conditions. Notwithstanding the above, nothing herein shall
|
120
|
+
supersede or modify the terms of any separate license agreement you may have
|
121
|
+
executed with Licensor regarding such Contributions.
|
122
|
+
|
123
|
+
6. Trademarks. This License does not grant permission to use the trade names,
|
124
|
+
trademarks, service marks, or product names of the Licensor, except as required
|
125
|
+
for reasonable and customary use in describing the origin of the Work and
|
126
|
+
reproducing the content of the NOTICE file.
|
127
|
+
|
128
|
+
7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
|
129
|
+
writing, Licensor provides the Work (and each Contributor provides its
|
130
|
+
Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
131
|
+
KIND, either express or implied, including, without limitation, any warranties
|
132
|
+
or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
133
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
134
|
+
appropriateness of using or redistributing the Work and assume any risks
|
135
|
+
associated with Your exercise of permissions under this License.
|
136
|
+
|
137
|
+
8. Limitation of Liability. In no event and under no legal theory, whether in
|
138
|
+
tort (including negligence), contract, or otherwise, unless required by
|
139
|
+
applicable law (such as deliberate and grossly negligent acts) or agreed to in
|
140
|
+
writing, shall any Contributor be liable to You for damages, including any
|
141
|
+
direct, indirect, special, incidental, or consequential damages of any character
|
142
|
+
arising as a result of this License or out of the use or inability to use the
|
143
|
+
Work (including but not limited to damages for loss of goodwill, work stoppage,
|
144
|
+
computer failure or malfunction, or any and all other commercial damages or
|
145
|
+
losses), even if such Contributor has been advised of the possibility of such
|
146
|
+
damages.
|
147
|
+
|
148
|
+
9. Accepting Warranty or Additional Liability. While redistributing the Work or
|
149
|
+
Derivative Works thereof, You may choose to offer, and charge a fee for,
|
150
|
+
acceptance of support, warranty, indemnity, or other liability obligations
|
151
|
+
and/or rights consistent with this License. However, in accepting such
|
152
|
+
obligations, You may act only on Your own behalf and on Your sole
|
153
|
+
responsibility, not on behalf of any other Contributor, and only if You agree
|
154
|
+
to indemnify, defend, and hold each Contributor harmless for any liability
|
155
|
+
incurred by, or claims asserted against, such Contributor by reason of your
|
156
|
+
accepting any such warranty or additional liability.
|
157
|
+
|
158
|
+
END OF TERMS AND CONDITIONS
|
data/README.md
ADDED
@@ -0,0 +1,182 @@
|
|
1
|
+
Ruby Client
|
2
|
+
===========
|
3
|
+
|
4
|
+
<a href="https://raw.githubusercontent.com/ArpNetworking/metrics-client-ruby/master/LICENSE">
|
5
|
+
<img src="https://img.shields.io/hexpm/l/plug.svg"
|
6
|
+
alt="License: Apache 2">
|
7
|
+
</a>
|
8
|
+
<a href="https://travis-ci.org/ArpNetworking/metrics-client-ruby/">
|
9
|
+
<img src="https://travis-ci.org/ArpNetworking/metrics-client-ruby.png"
|
10
|
+
alt="Travis Build">
|
11
|
+
</a>
|
12
|
+
[![Gem Version](https://badge.fury.io/rb/tsd_metrics.svg)](https://badge.fury.io/rb/tsd_metrics)
|
13
|
+
|
14
|
+
Client implementation for publishing metrics from Ruby applications.
|
15
|
+
|
16
|
+
|
17
|
+
Instrumenting Your Application
|
18
|
+
------------------------------
|
19
|
+
|
20
|
+
### Add Dependency
|
21
|
+
|
22
|
+
Determine the latest version of the Ruby client in [rubygems.org](https://rubygems.org/gems/tsd_metrics). Modify your Gemfile to include the Ruby Gems repository:
|
23
|
+
|
24
|
+
source "http://rubygems.org"
|
25
|
+
|
26
|
+
Add a dependency on the metrics client in your Gemfile:
|
27
|
+
|
28
|
+
gem "tsd_metrics" "VERSION"
|
29
|
+
|
30
|
+
### Initialization
|
31
|
+
|
32
|
+
The metrics library must be initialized before being used. The following example will configure the library to output metrics to the relative directory "./log/query.log":
|
33
|
+
|
34
|
+
```ruby
|
35
|
+
TsdMetrics.init(filename: Rails.root.join('log', 'query.log'))
|
36
|
+
```
|
37
|
+
|
38
|
+
The options accepted by TsdMetrics.init() and their defaults are:
|
39
|
+
```ruby
|
40
|
+
TsdMetrics.init({
|
41
|
+
filename: 'query.log' # Optional: the relative or absolute path to output metrics. Default: 'query.log' in the working directory
|
42
|
+
errorLogger: Logger.new(STDOUT) # Optional: a place to which mis-uses of the library can be logged. Expects methods info, warn, error.
|
43
|
+
rollLogs: true # Have the library do log rolling; not thread-safe! Setting to false means the library-user should have external log-rolling in place.
|
44
|
+
})
|
45
|
+
```
|
46
|
+
|
47
|
+
### Metrics
|
48
|
+
|
49
|
+
A new Metrics instance should be created for each unit of work. For example:
|
50
|
+
|
51
|
+
```ruby
|
52
|
+
metrics = TsdMetrics.buildMetric
|
53
|
+
```
|
54
|
+
|
55
|
+
Counters, timers and gauges are recorded against a metrics instance which must be closed at the end of a unit of work. After the Metrics instance is closed no further measurements may be recorded against that instance.
|
56
|
+
|
57
|
+
```ruby
|
58
|
+
metrics.incrementCounter("foo");
|
59
|
+
metrics.startTimer("bar");
|
60
|
+
// Do something that is being timed
|
61
|
+
metrics.stopTimer("bar");
|
62
|
+
metrics.setGauge("temperature", 21.7);
|
63
|
+
metrics.close();
|
64
|
+
```
|
65
|
+
|
66
|
+
### Counters
|
67
|
+
|
68
|
+
Surprisingly, counters are probably more difficult to use and interpret than timers and gauges. In the simplest case you can just starting counting, for example, iterations of a loop:
|
69
|
+
|
70
|
+
```ruby
|
71
|
+
arrayOfStrings.each { |string|
|
72
|
+
metrics.incrementCounter("strings");
|
73
|
+
...
|
74
|
+
}
|
75
|
+
```
|
76
|
+
|
77
|
+
However, what happens if listOfString is empty? Then no sample is recorded. To always record a sample the counter should be reset before the loop is executed:
|
78
|
+
|
79
|
+
```ruby
|
80
|
+
metrics.resetCounter("strings");
|
81
|
+
arrayOfStrings.each { |string|
|
82
|
+
metrics.incrementCounter("strings");
|
83
|
+
...
|
84
|
+
}
|
85
|
+
```
|
86
|
+
|
87
|
+
Next, if the loop is executed multiple times:
|
88
|
+
|
89
|
+
```ruby
|
90
|
+
arrayOfArrayOfStrings.each { |arrayOfStrings|
|
91
|
+
metrics.resetCounter("strings");
|
92
|
+
arrayOfStrings.each { |string|
|
93
|
+
metrics.incrementCounter("s");
|
94
|
+
...
|
95
|
+
}
|
96
|
+
}
|
97
|
+
```
|
98
|
+
|
99
|
+
The above code will produce a number of samples equal to the size of listOfListOfStrings (including no samples if listOfListOfStrings is empty). If you move the resetCounter call outside the outer loop the code always produces a single sample (even if listOfListOfStrings is empty). There is a significant difference between counting the total number of strings and the number of strings per list; especially, when computing and analyzing statistics such as percentiles.
|
100
|
+
|
101
|
+
Finally, if the loop is being executed concurrently for the same unit of work, that is for the same Metrics instance, then you could use a Counter object:
|
102
|
+
|
103
|
+
```ruby
|
104
|
+
final Counter counter = metrics.createCounter("strings");
|
105
|
+
arrayOfStrings.each { |string|
|
106
|
+
counter.increment();
|
107
|
+
...
|
108
|
+
}
|
109
|
+
```
|
110
|
+
|
111
|
+
The Counter object example extends in a similar way for nested loops.
|
112
|
+
|
113
|
+
### Timers
|
114
|
+
|
115
|
+
Timers are very easy to use. The only note worth making is that when using timers - either procedural or via objects - do not forget to stop/close the timer! If you fail to do this the client will log a warning and suppress any unstopped/unclosed samples.
|
116
|
+
|
117
|
+
The timer object allows a timer sample to be detached from the Metrics instance. For example:
|
118
|
+
|
119
|
+
```ruby
|
120
|
+
def threadFunc
|
121
|
+
final Timer t = metrics.createTimer("operation");
|
122
|
+
// Perform your operation
|
123
|
+
t.stop();
|
124
|
+
}
|
125
|
+
```
|
126
|
+
|
127
|
+
This is very useful in a concurrent system when executing and thus measuring the same event multiple times concurrently. The one caveat is to ensure the timer objects are stopped/closed before the Metrics instance is closed. Failing to do so will log a warning and suppress any samples stopped/closed after the Metrics instance is closed.
|
128
|
+
|
129
|
+
### Gauges
|
130
|
+
|
131
|
+
Gauges are the simplest metric to record. Samples for a gauge represent spot measurements. For example, the length of a queue or the number of active threads in a thread pool. Gauges are often used in separate units of work to measure the state of system resources, for example the row count in a database table. However, gauges are also useful in existing units of work, for example recording the memory in use at the beginning and end of each service request.
|
132
|
+
|
133
|
+
Building
|
134
|
+
--------
|
135
|
+
|
136
|
+
Links to prerequisites:
|
137
|
+
* [RVM](https://rvm.io/rvm/install) (w/ Ruby 1.9.3+)
|
138
|
+
|
139
|
+
Install Ruby version with RVM:
|
140
|
+
|
141
|
+
client-ruby> rvm install 1.9.3
|
142
|
+
|
143
|
+
Select Ruby version with RVM:
|
144
|
+
|
145
|
+
client-ruby> rvm 1.9.3
|
146
|
+
|
147
|
+
Building the gem:
|
148
|
+
|
149
|
+
client-ruby> gem build tsd_metrics.gemspec
|
150
|
+
|
151
|
+
Testing the gem:
|
152
|
+
|
153
|
+
client-ruby> rspec
|
154
|
+
|
155
|
+
Install the current version locally:
|
156
|
+
|
157
|
+
gem install --local /path_to_gem/tsd_metrics.gem
|
158
|
+
|
159
|
+
Using the local version is intended only for testing or development.
|
160
|
+
|
161
|
+
Frameworks
|
162
|
+
----------
|
163
|
+
|
164
|
+
It is common for Ruby frameworks to run in a multi-process mode for serving requests. Often, the
|
165
|
+
frameworks will using forking to setup new processes. Forking can be problematic as the client
|
166
|
+
creates a Ruby thread to write the log in the background. If the client is initialized before
|
167
|
+
the fork, the background writer thread will continue to run in the original process, but not
|
168
|
+
in the newly created process. This often manifests as an increasing write queue, but no data
|
169
|
+
written to the metrics log file. The following describes what steps are needed for frameworks
|
170
|
+
we have encountered.
|
171
|
+
|
172
|
+
### Passenger
|
173
|
+
|
174
|
+
No work is needed to make the client work under Phusion Passenger. Internally, we detect the fork
|
175
|
+
and re-initialize the client. Everything just works.
|
176
|
+
|
177
|
+
License
|
178
|
+
-------
|
179
|
+
|
180
|
+
Published under Apache Software License 2.0, see LICENSE
|
181
|
+
|
182
|
+
© Groupon Inc., 2014
|
data/Rakefile
ADDED
data/demo.rb
ADDED
@@ -0,0 +1,27 @@
|
|
1
|
+
# Copyright 2014 Groupon.com
|
2
|
+
#
|
3
|
+
# Licensed under the Apache License, Version 2.0 (the "License");
|
4
|
+
# you may not use this file except in compliance with the License.
|
5
|
+
# You may obtain a copy of the License at
|
6
|
+
#
|
7
|
+
# http://www.apache.org/licenses/LICENSE-2.0
|
8
|
+
#
|
9
|
+
# Unless required by applicable law or agreed to in writing, software
|
10
|
+
# distributed under the License is distributed on an "AS IS" BASIS,
|
11
|
+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
12
|
+
# See the License for the specific language governing permissions and
|
13
|
+
# limitations under the License.
|
14
|
+
|
15
|
+
require_relative 'lib/tsd_metrics'
|
16
|
+
filename = "my_logs.json"
|
17
|
+
|
18
|
+
TsdMetrics.init(filename)
|
19
|
+
# build metric, close
|
20
|
+
while true
|
21
|
+
metric = TsdMetrics.buildMetric
|
22
|
+
metric.setGauge("myGauge", 1 / ((Time.now.to_f ** 2) + 1))
|
23
|
+
metric.setGauge("myGauge2", 20)
|
24
|
+
metric.annotate("myAnnotation", "Hi there")
|
25
|
+
metric.close
|
26
|
+
sleep (0.5)
|
27
|
+
end
|
@@ -0,0 +1,59 @@
|
|
1
|
+
Query Log Format
|
2
|
+
================
|
3
|
+
|
4
|
+
Provides a platform for recording, aggregating, publishing and accessing metrics produced by your host system, shared resource, or application.
|
5
|
+
|
6
|
+
|
7
|
+
Versions
|
8
|
+
--------
|
9
|
+
|
10
|
+
### 2G *(Proposed)*
|
11
|
+
|
12
|
+
* *Example Not Available*
|
13
|
+
* *Schema Not Available*
|
14
|
+
|
15
|
+
Changes:
|
16
|
+
* Include time offset relative to initTimestamp on each timer sample.
|
17
|
+
|
18
|
+
### 2F *(Proposed)*
|
19
|
+
|
20
|
+
* *Example Not Available*
|
21
|
+
* *Schema Not Available*
|
22
|
+
|
23
|
+
Changes:
|
24
|
+
* Support for compound units (e.g. Megabytes per second).
|
25
|
+
* Fully self-describing:
|
26
|
+
* Include service name
|
27
|
+
* Include cluster name
|
28
|
+
* Include host name
|
29
|
+
|
30
|
+
### 2E
|
31
|
+
|
32
|
+
* [Example](query-log-example-2e.json)
|
33
|
+
* [Schema](query-log-schema-2e.json)
|
34
|
+
|
35
|
+
Changes:
|
36
|
+
* Wrap the metrics payload in a formatted container to better support general log routing and storage.
|
37
|
+
* The time, name and level fields must be serialized first and in that order.
|
38
|
+
* The time must be in ISO8601 with date, time and timezone.
|
39
|
+
|
40
|
+
### 2D
|
41
|
+
|
42
|
+
* [Example](query-log-example-2d.json)
|
43
|
+
* [Schema](query-log-schema-2d.json)
|
44
|
+
|
45
|
+
Changes:
|
46
|
+
* Expand counter, timer and gauge samples to include optional units.
|
47
|
+
* Switch finalTimestamp and initTimestamp annotations from epoch to ISO8601.
|
48
|
+
|
49
|
+
### 2C
|
50
|
+
|
51
|
+
* [Example](query-log-example-2c.json)
|
52
|
+
* [Schema](query-log-schema-2c.json)
|
53
|
+
|
54
|
+
Changes:
|
55
|
+
* First standardized JSON format.
|
56
|
+
|
57
|
+
### Pre-2C
|
58
|
+
|
59
|
+
All versions prior to 2C of the file format and are considered *deprecated*.
|
@@ -0,0 +1,55 @@
|
|
1
|
+
{
|
2
|
+
"title": "Query Log",
|
3
|
+
"description": "log file entry for ingestion by tsd aggregator",
|
4
|
+
"type":"object",
|
5
|
+
"$schema": "http://json-schema.org/draft-04/schema#",
|
6
|
+
"properties":{
|
7
|
+
"annotations": {
|
8
|
+
"type":"object",
|
9
|
+
"properties":{
|
10
|
+
"finalTimestamp": {
|
11
|
+
"type":"string"
|
12
|
+
},
|
13
|
+
"initTimestamp": {
|
14
|
+
"type":"string"
|
15
|
+
}
|
16
|
+
},
|
17
|
+
"required": ["initTimestamp", "finalTimestamp"]
|
18
|
+
},
|
19
|
+
"counters": {
|
20
|
+
"type":"object",
|
21
|
+
"properties":{ },
|
22
|
+
"additionalProperties": {
|
23
|
+
"type": "array",
|
24
|
+
"items": {
|
25
|
+
"type": "number"
|
26
|
+
}
|
27
|
+
}
|
28
|
+
},
|
29
|
+
"gauges": {
|
30
|
+
"type":"object",
|
31
|
+
"properties":{ },
|
32
|
+
"additionalProperties": {
|
33
|
+
"type": "array",
|
34
|
+
"items": {
|
35
|
+
"type": "number"
|
36
|
+
}
|
37
|
+
}
|
38
|
+
},
|
39
|
+
"timers": {
|
40
|
+
"type":"object",
|
41
|
+
"properties":{ },
|
42
|
+
"additionalProperties": {
|
43
|
+
"type": "array",
|
44
|
+
"items": {
|
45
|
+
"type": "number"
|
46
|
+
}
|
47
|
+
}
|
48
|
+
},
|
49
|
+
"version": {
|
50
|
+
"type":"string",
|
51
|
+
"pattern": "^2c$"
|
52
|
+
}
|
53
|
+
},
|
54
|
+
"required": ["annotations", "counters", "timers", "gauges", "version"]
|
55
|
+
}
|
@@ -0,0 +1,69 @@
|
|
1
|
+
{
|
2
|
+
"$schema": "http://json-schema.org/draft-04/schema#",
|
3
|
+
"definitions": {
|
4
|
+
"sampleObject" : {
|
5
|
+
"type": "object",
|
6
|
+
"properties" : {
|
7
|
+
"unit": {
|
8
|
+
"type": "string",
|
9
|
+
"enum": ["nanosecond","microsecond", "millisecond", "second", "minute", "hour", "day", "week", "bit", "byte", "kilobit", "kilobyte", "megabit", "megabyte", "gigabit", "gigabyte", "terabyte", "petabyte"]
|
10
|
+
},
|
11
|
+
"value": {
|
12
|
+
"type": "number"
|
13
|
+
}
|
14
|
+
}
|
15
|
+
},
|
16
|
+
"dataElement": {
|
17
|
+
"type": "object",
|
18
|
+
"properties": {
|
19
|
+
"values": {
|
20
|
+
"type": "array",
|
21
|
+
"items": {
|
22
|
+
"$ref": "#/definitions/sampleObject"
|
23
|
+
}
|
24
|
+
}
|
25
|
+
}
|
26
|
+
},
|
27
|
+
"metricsList": {
|
28
|
+
"type": "object",
|
29
|
+
"additionalProperties": {
|
30
|
+
"$ref": "#/definitions/dataElement"
|
31
|
+
}
|
32
|
+
}
|
33
|
+
},
|
34
|
+
|
35
|
+
"title": "Query Log",
|
36
|
+
"description": "log file entry for ingestion by tsd aggregator",
|
37
|
+
"type":"object",
|
38
|
+
|
39
|
+
"properties":{
|
40
|
+
"annotations": {
|
41
|
+
"type":"object",
|
42
|
+
"properties": {
|
43
|
+
"finalTimestamp": {
|
44
|
+
"type":"string",
|
45
|
+
"format": "date-time"
|
46
|
+
},
|
47
|
+
"initTimestamp": {
|
48
|
+
"type":"string",
|
49
|
+
"format": "date-time"
|
50
|
+
}
|
51
|
+
},
|
52
|
+
"required": ["initTimestamp", "finalTimestamp"]
|
53
|
+
},
|
54
|
+
"counters": {
|
55
|
+
"$ref": "#/definitions/metricsList"
|
56
|
+
},
|
57
|
+
"gauges": {
|
58
|
+
"$ref": "#/definitions/metricsList"
|
59
|
+
},
|
60
|
+
"timers": {
|
61
|
+
"$ref": "#/definitions/metricsList"
|
62
|
+
},
|
63
|
+
"version": {
|
64
|
+
"type":"string",
|
65
|
+
"pattern": "^2d$"
|
66
|
+
}
|
67
|
+
},
|
68
|
+
"required": ["annotations", "version"]
|
69
|
+
}
|