-
Notifications
You must be signed in to change notification settings - Fork 11
/
README
212 lines (154 loc) · 6.6 KB
/
README
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
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
README file for the Application Heartbeats Project (Heartbeats)
-----------------------------------------------------------------
The contents of this README file are:
Project Description
Getting Started
Implementations
Directory Organization
Documentation for Heartbeats
Environment Variables for Heartbeats
Shared Memory Implementations
Testing Heartbeats
Using Power Monitoring
Team Members
Project Description
---------------------------------------
The Application Heartbeats framework provides a simple, standardized way for
applications to monitor their performance and make that information available
to external observers. The framework allows programmers to express their
application's goals and the progress that it is making using a simple API.
This progress can then be observed by either the application itself or an
external system (such as the OS or another application) so that the application
or system can be adapted to make sure the goals are met.
The 2.0 version adds support for accuracy and power monitoring. For other
changes, or if upgrading from a previous release, please see the NEWS file.
Source code available at:
https://github.com/libheartbeats/heartbeats
Original Heartbeats code, website, and discussion group are at:
http://code.google.com/p/heartbeats/downloads/list
http://groups.csail.mit.edu/carbon/heartbeats/
http://groups.google.com/group/heartbeatsapi
Getting Started
---------------------------------------
To build the libraries, run:
$ make
To install the libraries to the local system, run:
$ make install
Headers are installed to /usr/local/include/heartbeats.
The libraries are installed to /usr/local/lib.
To remove the libraries from the local system, run:
$ make uninstall
Implementations
---------------------------------------
There are three main Heartbeats libraries available to choose from:
libhb-shared.so
Headers: heartbeat.h, heartbeat-types.h
Performance monitoring.
libhb-acc-shared.so
Headers: heartbeat-accuracy.h, heartbeat-accuracy-types.h
Performance and accuracy monitoring.
libhb-acc-pow-shared.so
Headers: heartbeat-accuracy-power.h, heartbeat-accuracy-power-types.h
Performance, accuracy, and power monitoring.
Uses the hb-energy interface to collect energy readings, which the library
converts to power values.
hb-energy implementations:
libhb-energy-dummy.so
A dummy implementation.
libhb-energy-msr.so
Collects energy readings from an Intel Model-Specific Register (MSR).
Requires the "msr" kernel module to be loaded.
libhb-energy-odroidxue.so
Reads INA-231 power sensors on an ODROID-XU+E development board.
Requires the sensors to be enabled.
libhb-energy-wattsup.so
Reads power from a WattsUp? Pro external power monitor via USB.
This library is disabled by default from the build because of its
dependency on another library:
https://github.com/libwattsup/wattsup
libhb-energy.so
Contains all implementations, with the hb-energy interface disabled.
For further information, see the Using Power Monitoring section.
Directory Organization
---------------------------------------
/
|-doc/ -- Documentation
|-html -- Documentation in HTML format
|-latex -- Documentation in latex format
|-inc/ -- Header files
|-src/ -- Source files
Documentation for Heartbeats
---------------------------------------
The documentation for the Heartbeats framework is created with Doxygen.
To build the documentation, run:
doxygen heartbeats_doc
Environment Variables for Heartbeats
---------------------------------------
In the Heartbeats framework, Heartbeat-enabled applications signal
their presence to the rest of the world by writing a file to a special
directory. Currently, this directory is specified by an environment
variable: HEARTBEAT_ENABLED_DIR. Before running the tests, users
should define this variable to point to a directory in which they have
read and write permissions.
Shared Memory Implementations
---------------------------------------
Heartbeats use shared memory to support inter-process communication.
However, they do not clean up after themselves - that is the user's
responsbility. The following is a simple script to free memory after
processes complete:
#!/bin/bash
# Cleanup heartbeats shared memory
# Connor Imes
# 2015-01-15
MEMS=`ipcs | grep $USER | awk '{print $2}'`
for k in $MEMS
do
echo Freeing $k
ipcrm -m $k
done
Testing Heartbeats
---------------------------------------
The latest release of the Heartbeats framework comes with a set of
available tests that can be used to familiarize yourself with this
API. You can run one of our two examples, using the following command
(use it from the root directory of the Heartbeats framework):
make bench-tp
to use the throughput example, or
make bench-lat
to use the latency example
Using Power Monitoring
---------------------------------------
The following applies to libhb-acc-pow-shared.
Power/energy readings require hardware resources to provide data to software.
We therefore introduce the hb-energy interface to allow Heartbeats to access
this information. Some implementations are included, the most likely of which
to be used is hb-energy-msr, which polls an Intel Model-Specific Register.
Of course, users can write their own implementations if they have different
resources - see the included ones for examples.
If you want to use a single hb-energy implementation (e.g. hb-energy-msr) to
collect metrics, you can define HB_ENERGY_IMPL in your code in order to use the
header functions defined in hb-energy.h. Using the interface functions allows
changing which energy implementation library you use at build time without
modifying code, only the library you link with. E.g., you can make a call to
hb_energy_impl_alloc() and pass the pointer returned to
heartbeat_acc_pow_init() without the code needing to know which implementation
is active.
If you wish to read energy data from multiple sources, you will need to write
your own hb-energy implementation that wraps around existing and/or new
hb-energy implementations which are compiled WITHOUT HB_ENERGY_IMPL, meaning
you will need to access their functions directly. For example, if you need to
combine MSR and WattsUp reading, you will implement hb_energy_read_total(), and
from there make calls to both hb_energy_read_total_msr() and
hb_energy_read_total_wattsup(). This is easily achieved by linking with
libhb-energy.so.
Team Members
---------------------------------------
Version 2.x:
Connor Imes
Henry Hoffmann
Version 1.x:
Henry Hoffmann
Jonathan Eastep
Marco D. Santambrogio
Jason E. Miller
Anant Agarwal