{"id":13817024,"url":"https://github.com/libheartbeats/heartbeats","last_synced_at":"2026-01-10T21:59:07.534Z","repository":{"id":22150544,"uuid":"25481775","full_name":"libheartbeats/heartbeats","owner":"libheartbeats","description":"Heartbeats API v2.0","archived":false,"fork":false,"pushed_at":"2016-05-16T18:02:25.000Z","size":68,"stargazers_count":7,"open_issues_count":1,"forks_count":11,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-11-19T14:42:40.445Z","etag":null,"topics":["accuracy","feedback-mechanism","heartbeat","performance","power","profiler"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/libheartbeats.png","metadata":{"files":{"readme":"README","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-10-20T19:03:52.000Z","updated_at":"2021-08-26T04:25:55.000Z","dependencies_parsed_at":"2022-08-20T20:10:28.847Z","dependency_job_id":null,"html_url":"https://github.com/libheartbeats/heartbeats","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libheartbeats%2Fheartbeats","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libheartbeats%2Fheartbeats/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libheartbeats%2Fheartbeats/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libheartbeats%2Fheartbeats/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/libheartbeats","download_url":"https://codeload.github.com/libheartbeats/heartbeats/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254397972,"owners_count":22064591,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accuracy","feedback-mechanism","heartbeat","performance","power","profiler"],"created_at":"2024-08-04T06:00:31.580Z","updated_at":"2026-01-10T21:59:07.465Z","avatar_url":"https://github.com/libheartbeats.png","language":"C","funding_links":[],"categories":["Repositories"],"sub_categories":[],"readme":"README file for the Application Heartbeats Project (Heartbeats)\n-----------------------------------------------------------------\n\nThe contents of this README file are:\n\n  Project Description\n  Getting Started\n  Implementations\n  Directory Organization\n  Documentation for Heartbeats\n  Environment Variables for Heartbeats\n  Shared Memory Implementations\n  Testing Heartbeats\n  Using Power Monitoring\n  Team Members\n\n\nProject Description\n---------------------------------------\n\nThe Application Heartbeats framework provides a simple, standardized way for\napplications to monitor their performance and make that information available\nto external observers. The framework allows programmers to express their\napplication's goals and the progress that it is making using a simple API.\nThis progress can then be observed by either the application itself or an\nexternal system (such as the OS or another application) so that the application\nor system can be adapted to make sure the goals are met.\n\nThe 2.0 version adds support for accuracy and power monitoring. For other\nchanges, or if upgrading from a previous release, please see the NEWS file.\n\nSource code available at:\n\n  https://github.com/libheartbeats/heartbeats\n\nOriginal Heartbeats code, website, and discussion group are at:\n\n  http://code.google.com/p/heartbeats/downloads/list\n  http://groups.csail.mit.edu/carbon/heartbeats/\n  http://groups.google.com/group/heartbeatsapi\n\n\nGetting Started\n---------------------------------------\n\nTo build the libraries, run:\n\n$ make\n\nTo install the libraries to the local system, run:\n\n$ make install\n\nHeaders are installed to /usr/local/include/heartbeats.\nThe libraries are installed to /usr/local/lib.\n\nTo remove the libraries from the local system, run:\n\n$ make uninstall\n\n\nImplementations\n---------------------------------------\n\nThere are three main Heartbeats libraries available to choose from:\n\n  libhb-shared.so\n    Headers: heartbeat.h, heartbeat-types.h\n    Performance monitoring.\n  libhb-acc-shared.so\n    Headers: heartbeat-accuracy.h, heartbeat-accuracy-types.h\n    Performance and accuracy monitoring.\n  libhb-acc-pow-shared.so\n    Headers: heartbeat-accuracy-power.h, heartbeat-accuracy-power-types.h\n    Performance, accuracy, and power monitoring.\n    Uses the hb-energy interface to collect energy readings, which the library\n    converts to power values.\n\nhb-energy implementations:\n\n  libhb-energy-dummy.so\n    A dummy implementation.\n  libhb-energy-msr.so\n    Collects energy readings from an Intel Model-Specific Register (MSR).\n    Requires the \"msr\" kernel module to be loaded.\n  libhb-energy-odroidxue.so\n    Reads INA-231 power sensors on an ODROID-XU+E development board.\n    Requires the sensors to be enabled.\n  libhb-energy-wattsup.so\n    Reads power from a WattsUp? Pro external power monitor via USB.\n    This library is disabled by default from the build because of its\n    dependency on another library:\n      https://github.com/libwattsup/wattsup\n  libhb-energy.so\n    Contains all implementations, with the hb-energy interface disabled.\n\nFor further information, see the Using Power Monitoring section.\n\n\nDirectory Organization\n---------------------------------------\n\n/\n|-doc/    -- Documentation\n  |-html  -- Documentation in HTML format\n  |-latex -- Documentation in latex format\n|-inc/    -- Header files\n|-src/    -- Source files\n\n\nDocumentation for Heartbeats\n---------------------------------------\n\nThe documentation for the Heartbeats framework is created with Doxygen.\nTo build the documentation, run:\n\n  doxygen heartbeats_doc\n\n\nEnvironment Variables for Heartbeats\n---------------------------------------\n\nIn the Heartbeats framework, Heartbeat-enabled applications signal\ntheir presence to the rest of the world by writing a file to a special\ndirectory.  Currently, this directory is specified by an environment\nvariable: HEARTBEAT_ENABLED_DIR.  Before running the tests, users\nshould define this variable to point to a directory in which they have\nread and write permissions.\n\n\nShared Memory Implementations\n---------------------------------------\n\nHeartbeats use shared memory to support inter-process communication.\nHowever, they do not clean up after themselves - that is the user's\nresponsbility.  The following is a simple script to free memory after\nprocesses complete:\n\n#!/bin/bash\n# Cleanup heartbeats shared memory\n# Connor Imes\n# 2015-01-15\n\nMEMS=`ipcs | grep $USER | awk '{print $2}'`\nfor k in $MEMS\ndo\n        echo Freeing $k\n        ipcrm -m $k\ndone\n\n\nTesting Heartbeats\n---------------------------------------\n\nThe latest release of the Heartbeats framework comes with a set of\navailable tests that can be used to familiarize yourself with this\nAPI. You can run one of our two examples, using the following command\n(use it from the root directory of the Heartbeats framework):\n\n  make bench-tp\n\nto use the throughput example, or\n\n  make bench-lat\n\nto use the latency example\n\n\nUsing Power Monitoring\n---------------------------------------\n\nThe following applies to libhb-acc-pow-shared.\n\nPower/energy readings require hardware resources to provide data to software.\nWe therefore introduce the hb-energy interface to allow Heartbeats to access\nthis information. Some implementations are included, the most likely of which\nto be used is hb-energy-msr, which polls an Intel Model-Specific Register.\nOf course, users can write their own implementations if they have different\nresources - see the included ones for examples.\n\nIf you want to use a single hb-energy implementation (e.g. hb-energy-msr) to\ncollect metrics, you can define HB_ENERGY_IMPL in your code in order to use the\nheader functions defined in hb-energy.h. Using the interface functions allows\nchanging which energy implementation library you use at build time without\nmodifying code, only the library you link with. E.g., you can make a call to\nhb_energy_impl_alloc() and pass the pointer returned to\nheartbeat_acc_pow_init() without the code needing to know which implementation\nis active.\n\nIf you wish to read energy data from multiple sources, you will need to write\nyour own hb-energy implementation that wraps around existing and/or new\nhb-energy implementations which are compiled WITHOUT HB_ENERGY_IMPL, meaning\nyou will need to access their functions directly. For example, if you need to\ncombine MSR and WattsUp reading, you will implement hb_energy_read_total(), and\nfrom there make calls to both hb_energy_read_total_msr() and\nhb_energy_read_total_wattsup(). This is easily achieved by linking with\nlibhb-energy.so.\n\n\nTeam Members\n---------------------------------------\n\nVersion 2.x:\n  Connor Imes\n  Henry Hoffmann\n\nVersion 1.x:\n  Henry Hoffmann\n  Jonathan Eastep\n  Marco D. Santambrogio\n  Jason E. Miller\n  Anant Agarwal\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flibheartbeats%2Fheartbeats","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flibheartbeats%2Fheartbeats","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flibheartbeats%2Fheartbeats/lists"}