LibreSocial · Documentation

Monitoring — the SkyEye-derived statistics over-overlay

Deep-dive page: the com.p2pframework.monitoring OSGi bundle plus com.p2pframework.datacollection (in com.p2pframework) and com.p2pframework.message.aggregate (also in com.p2pframework) — i.e. sensors, the DHT-derived aggregation tree, and the local statistics writers.

Supersession note: the design of this component is SkyEye.KOM (Graffi 2008), the OSGi prototype that first ran inside LifeSocial.KOM is Groß 2009, and the consolidated design/parameter statement is the journal paper SkyEye 2017. The code in the tree today is not that prototype: it is the simplified re-implementation written by the University of Paderborn project group 2011/12 (PG 2011, PG 2012), carried forward by the 2025 revival (Imam 2025) and the 2026 Java-17/bnd migration. Capacity advertising, capacity-based peer search, support peers and the convex-hull watchdog (Disterhöft 2016) exist in the publications only — they are not implemented in the 2026 source.

Purpose

The component gives every node a network-wide view of the running system ("the Oracle view") without a management server:

  1. Sensing — each framework subsystem exposes numeric attributes (Attribute = name, value, unit, aggregation strategy, sensor id, participant count). com.p2pframework.datacollection measures the raw per-message/per-storage byte volumes that feed those attributes.
  2. Aggregation — every node periodically pushes its attributes up a tree derived from the DHT key space; intermediate nodes aggregate, the root coordinator computes the global statistics.
  3. Dissemination — the global view travels back down as ACK/global messages, so every node holds the aggregated values locally (proactive, push-based — no query has to be issued to see the state).
  4. Local persistence / export — statistics are written to SQLite, text, .dat/CSV or gnuplot files and can be served as JSON over the web plugin, which is what testbed evaluations plot from.

Consumers today: the console command monitor, the test framework com.p2pframework.tester, and org.lifesocial.plugin.webprovider (JSON dashboards). Nothing in the plugin layer performs closed-loop reconfiguration on top of the statistics — the MAPE loop of Graffi 2010 was demonstrated in simulation/testbed, not shipped here.

Current implementation (as of 2026)

Bundle com.p2pframework.monitoring (38 Java files, ~3 700 lines under src/)

Source/com.p2pframework.monitoring/bnd.bnd: Bundle-RequiredExecutionEnvironment: JavaSE-17, Bundle-ActivationPolicy: lazy, Bundle-Activator: com.p2pframework.monitoring.MonitoringPlugin, -dsannotations: *, Bundle-ClassPath bundling log4j-1.2.15.jar and sqlite-jdbc-3.8.7.jar. The OSGi-INF XML descriptors were replaced by @Component/@Reference annotations in the 2026 branch (git: "Translate OSGI-INF XML to OSGi component and service annotations", "Replace JavaSE-1.7 with JavaSE-17 in all bnd files", "Add slf4j dependency to monitoring bundle").

File (under src/com/p2pframework/monitoring/) Lines Role
MonitoringPlugin.java 188 singleton OSGi component (IMonitoringPlugin, itself a Sensor); starts/stops the thread; collects Sensor services
MonitoringThread.java 236 5 s sampling loop: creates an AggregationChannel, reads sensor attributes, feeds visualizer + writer service
console/MonitorCommands.java, ui/{Start,Stop}Monitoring…, ui/StartGUI…, ui/StartBulletinBoard… 130/71 Equinox CommandProvider monitor [start\|stop\|status\|gui\|metricName:]; Eclipse RCP AbstractHandlers wired in plugin.xml
statoutput/component/StatisticWriterServiceImpl.java 975 SQLite/text/dat/CSV/gnuplot output, file rotation, snapshots
statoutput/component/sql/MonitoringSQLHelper.java 55 SQLite schema + query views
sqlite2gnuplot/OnlyPlotOneNodeGlobal.java, SQLiteToGnuplot*.java 406/150/65 offline plotting helpers
config/component/ConfigServiceImpl.java, logging/component/LoggingServiceImpl.java 147/57 bundle-local config from MyConfig.txt; ILoggingService
data/{GlobalStatistics,SingleStatistics,Attribute,Peer,PeerList}.java 56–93 SingleStatistics.AggregationType = SUM, COUNT, MEAN, MEDIAN, VARIANCE, MAX, MIN, SUMOFSQUARES, STANDARDDEVIATION
message/**, loadBalancing/LoadBalancingInfo.java 68–102 legacy SkyEye DTOs (see below)

Wiring (verified): MonitoringPlugin injects Framework, IStatisticWriterService (mandatory) and IStatisticVisualizer (no @Reference), and binds every OSGi Sensor service dynamically (@Reference(name="Sensor", cardinality=MANDATORY, policy=DYNAMIC)). MonitoringThread.run() calls framework.getMessageDispatcher().createAggregationChannel(name) and registers three built-in sensors — framework.getNetwork(), framework.getMessageDispatcher(), framework.getStorageDispatcher() — plus all plugin-provided sensors, then registers itself as GlobalAttributeCallback. Sample period is hard-coded heartBeat = 5000 ms; global values are stored under names prefixed GLOBAL_; Runtime.gc() is invoked every round.

The aggregation tree: com.p2pframework.message.aggregate (bundle com.p2pframework)

Source/com.p2pframework/src/com/p2pframework/message/aggregate/ — AggregationServer (386 l), AggregationChannel (114 l), Aggregator, CollectionAggregator, AggregationStrategy, Attribute, AggregateMessage, Sensor, GlobalAttributeCallback. This is the SkyEye tree, implemented as a trie over the DHT identifier space:

Sensor side: com.p2pframework.datacollection (6 files, 531 lines)

Measuring.collect(int enabled, String name, String type, Object o) is called at 62 sites inside com.p2pframework. Implementations:

Metric families exposed by the built-in sensors (constants verified in PastryNetwork, PastryMessageDispatcher, PastryMessageChannel, AggregationChannel, PastryStorageDispatcher): NETWORK_DATA_SENT(_RATE), NETWORK_DATA_RECEIVED(_RATE), NETWORK_MESSAGES_* incl. MESSAGES_DROPPED_COUNT, NETWORK_NODES, NETWORK_MEMORY_USAGE_SIZE, NETWORK_MEMORY_TOTAL_SIZE, NETWORK_PASTRY_DATA_*, NETWORK_NODE_JOINNETWORK_TIME, NETWORK_USER_REGISTRATION_TIME, MESSAGEDISPATCHER_MESSAGES_* incl. MESSAGES_LOST, NULL_POINTER, OTHER_EXCEPTION, and STORAGEDISPATCHER_USED_SIZE, …_LOOKUP_TIME_AVG, …_RETRIEVETIME, …_STORETIME, …_MESSAGE_HOPCOUNT, …_NUM_STORED_LOCAL_OBJECTS/REPLICATIONS, …_STORAGE_DATA_STORED/RETRIEVED. Most are emitted three times as _MIN/_MAX/_MEAN; counters use sum, latencies mean, minima smallestNonNegative.

End-to-end delay in the 2017 paper's sense is not a single first-class metric here. The closest current measurements are NETWORK_NODE_JOINNETWORK_TIME, NETWORK_USER_REGISTRATION_TIME (PastryTopicChannel.registTime), STORAGEDISPATCHER_LOOKUP_TIME_AVG, …_STORETIME/…_RETRIEVETIME, …_MESSAGE_HOPCOUNT and the aggregation-round timeOverhead clock offset. The SkyEye "E2E delay" metric itself (probe pairs sent through the overlay) has no implementation in this tree.

Output and activation

StatisticWriterServiceImpl (@Component(name="com.p2pframework.monitoring.StatisticWriterService")) is throttled to one write per 5 s, targets <user.dir>/SkyEyeData/Monitoring/Statistics (key STAT_OUPUT_DIR, note the typo), rotates text files at 10 MB (MAX_TEXT_OUTPUT_FILE_SIZE), snapshots every SNAPSHOT_INTERVAL = 3600 s, and enables outputs via LibreSocialConfig.txt flags — all four default to 0: monitoringToGnuplot, monitoringToSQLite, monitoringToDat, monitoringToCSV. SQLite schema (MonitoringSQLHelper): tables monitoring(ID, STAT, TIMESTAMP, VALUE) and stats(ID, NAME, TYPE, MEASURE) plus views list_data_rows, list_data_cols, list_stats, which the plotting helpers consume. Activation: autoStartMonitoring (default 0) makes org.lifesocial.loginplugin.component.LoginComponent (bundle org.lifesocial.plugin.loginplugin) call MonitoringPlugin.getInstance().startMonitoring() on login; otherwise the console command starts it. monitorDataVisual = 0 disables the in-memory visualizer history; monitoring.metricName: reads back MonitoringThread.localStatistics.

External consumers: com.p2pframework.tester (Master, TestCase{Login,Logout,Register}) and org.lifesocial.plugin.webprovider — PluginHandlers/MonitoringPluginHandler registers as a MonitoringClient and serves /monitoring/getmetrics (metric list) and /monitoring/getdata?metric=… (JSON time series, historySize = 30, historyStep = 120, MAX_DATAROW_ELEMENTS = 100) through Jetty.

Known gaps in the current build. (a) IStatisticVisualizer is injected but no implementation of the interface exists anywhere in Source/ — monitor gui / StartGUICommandHandler therefore dereference a null visualizer. (b) The exported packages com.p2pframework.monitoring.message, .message.query, .message.support, plus loadBalancing.LoadBalancingInfo and data.Peer/PeerList, are SkyEye DTOs (QueryRequest with GLOBAL_PEER_LIST/ALL_CAPACITY_NAMES/DNF, SupportRequest*, SupportForwardRequest, TopologyManagementContent, PropagateContent, LocalUpdateContent, Notfication) that no code in the tree references — grep finds zero uses outside the bundle itself. (c) The bundle-local config/MyConfig.txt still carries SkyEye-era keys (TREE_SPLITTING_FACTOR=2, T_MIN=-1, T_MAX=2, T_SUPPORT=20, LOADBLANCING_TIME=60000, SUPPORT_PEER_TIME=60000, STAT_UPDATE_TIME=5000, CAPACITY_UPDATE_TIME=5000, QUERY_TIMEOUT=10000) that ConfigServiceImpl loads but nothing consumes; the effective parameters live in AggregationServer and LibreSocialConfig.txt. The javadoc trace quap2p.dims.util.osgi.core.config.api.IConfigService is the fossil of the 2009 quap2p.dims.* layout.

Design options and decision

The publications debate three topologies for DIMS (distributed information management systems); the 2017 journal paper states the comparison explicitly, the 2009 master thesis supplies the taxonomy (Astrolabe, Willow, SOMO, SDIMS, CONE, T-Man, proactive epidemic aggregation; single-tree vs multi-tree, structured vs unstructured). The framework sources contain no design notes of their own, so the rationale below is reconstructed from the cited papers; the measured numbers are quoted from them.

Option Mechanism Cost/quality in the published evaluation Why not chosen
Centralised collector (monitoring server / SNMP-style) one manager polls or receives from all peers trivial to implement, exact view single point of failure and O(N) state/bandwidth at one node — incompatible with a purely decentralised OSN that has no server; ruled out in Graffi 2008
Gossip / push-sum (unstructured, e.g. Gnutella 0.6, Pastry Push-Sum) flood-and-sum over gossip links 2017 comparison: absolute error ≈ ±0.7 against ±0.1 for the tree, slower convergence too imprecise for rule loops, and the same accuracy costs more messages
DHT-derived tree (SkyEye) — implemented domains from the ID space, coordinator = key owner, commutative/associative aggregation bottom-up, dissemination on ACKs top-down 2017: error ≈ ±0.1, 512 B/min for the monitoring layer at UI = 30 s; O(log N) depth; tree depth stabilises under churn; 1–3 updates/peer/interval in 2008 —

Decision drivers recorded in the papers (Graffi 2008, Graffi 2009, Graffi 2017):

  1. Zero topology maintenance. The tree is computed, not joined: coordinator = peer responsible for the domain key, so route(key,msg)/isMyKey(key) (resp(key)) is the only overlay API required. That is why the 2011/12 code needed only isResponsibleFor() and a level loop — and why node join/leave self-heals.
  2. Overlay independence through a single ID space S_ID = [0,1] with a bijective mapping from the DHT space (Chord 2^160, Kademlia 2^128, Pastry 160 bit). This survives in the code as network/freepastry/PastryID.convertToSkyEyeId() / convertToFreePastryId() (BigDecimal representation).
  3. Constant message size — aggregation must be commutative and associative (count/sum/min/max, avg/variance/stddev), which excludes list concatenation. Groß 2009 showed the failure mode quantitatively: concatenation-based capacity aggregation made bandwidth grow toward the upper levels, so "the tree does not scale without filters or incremental updates". The 2011/12 code keeps only fixed-size scalar attributes — it accepts the scaling property by dropping capacity lists, and with them capacity-based peer search, later revived separately as CapSearch 2017 and the capacity management protocol of Graffi 2020.
  4. Proactive (push) rather than reactive (query): every node holds the global view locally, so plugins and rule loops read memory instead of issuing queries.
  5. Overlay choice matters for cost, not quality: identical monitoring accuracy on Chord and Pastry, but 4.6 hops / 26 294 B/min per peer on Chord vs ~1 hop / 1032 B/min on Pastry — one reason the framework standardised on (a heavily modified) FreePastry.

Parameter choices in the 2026 code differ from the published optimum, and this is a real inconsistency rather than a documentation nicety: the papers recommend UI = 30 s and β = 4 (UI = 60 s costs 1.5 absolute error points, UI = 15 s doubles cost for negligible gain, β barely affects traffic), while AggregationServer ships timeStep = 5000 ms and splitFactor = 8. The 5 s interval matches the testbed interval of Graffi 2010 (UI = 5 s, ~110 B/s per peer for system metrics, ~3 KB/s per peer in the 37-PC testbed) and Groß 2009 (≈3 KB/s per peer at 5 s, ≈200 B/s at 30–60 s, ~2 hops mean, churn up to 50 % survived, stabilisation ≈ 250 s, transient peer-count overshoot 575 instead of 500) — i.e. the code was tuned for short lab runs, not for the 2017 recommendation.

Security/robustness. The tree is attackable: Disterhöft & Graffi 2016 taxes it with ATParent/ATChild/ATRandom/ATRoot/ATEmpty/ATUpwards/ATDownwards/ATDoNothing and free-riding: relative errors up to 998 % unprotected, cut to 2 %/6 %/18 % (factor 2 manipulation, 5/10/20 % malicious ratio) by the DOMiNo convex-hull watchdog — modified Z-score over MAD (threshold 3.5, best configuration β = 96), structural checks (source ID inside the expected domain range, nonce-checked ACKs, min ≤ mean ≤ max, sumOfSquares ≤ max²·count) and multi-interval voting before discarding. None of that is in AggregationServer, which trusts every received attribute set; "Secure Monitoring" was still listed as a planned extension in PG 2013.

Technical details

Identifier space. FreePastry 160-bit IDs map onto BigDecimal ∈ [0,1) (PastryID.getBigDecimalRepresentation(), PastryIdConverter.convertToSkyEyeId/convertToFreePastryId). Level l domain boundaries are multiples of 8^-l; the domain key is the mid-point of the segment containing the local ID. Responsibility is answered by the overlay (Network.isResponsibleFor(ID)), so the tree is a trie projected onto the DHT.

Message format. AggregateMessage extends GenericMessage<Hashtable<String, Attribute<Serializable>>> (serialVersionUID 2890452517839981852L) with boolean global and long timeOverhead. Attribute<T> carries strategy, name, value, unit, sensorID, participants; participants is summed by Aggregator.aggregate(Attribute) and is the closest thing to a sample count. Transmission uses the ordinary message channel (channel com.p2pframework.Backend), not a dedicated one — hence the flat 28 000-byte charge in MeasuringMessageImpl for monitoring traffic rather than a per-message accounting.

Round scheduling and time alignment. Timer.scheduleAtFixedRate(task, timeStep, timeStep); on ACK receipt the node re-creates the task with delay = timeStep + scheduledExecutionTime − now − timeDelay (clamped at 0, negative delays logged and reset). Nodes that miss a round are simply absent from previousRounds; there is no SkyEye toldMetrics staleness timeout (1.5–2.0 × UI) and no retransmission — reliability is "best effort, next round".

Sensor registration. Sensor is a one-method interface (Hashtable<String, Attribute<Serializable>> getAttributes()), implemented by PastryNetwork, PastryMessageDispatcher, PastryStorageDispatcher, AggregationChannel and MonitoringPlugin itself (a single DUMMY_METRIC counter). Plugins add sensors by publishing the Sensor OSGi service; AggregationChannel.addSensor records agent.getClass().toString() as the sensor id, and AggregationChannel.receive filters global attributes by that id before calling GlobalAttributeCallback.receiveGlobalAttribute — a plugin therefore only sees values of its own sensors.

Aggregation strategies (AggregationStrategy): assign, bool, nonInteger, trueToHash, collectionRetainAll, multiMapAddAbortIfNull, multiMapAddAbortIfLeafsComplete, smallestNonNegative, smallest, greatest, sum, mean, joinCollection, orCollection. The first group is shared with the DDS fan-out/aggregation machinery (Aggregator also aggregates DoneMessages for PrefixHashTree/DDS), which is why monitoring and DDS share one aggregator class.

Integration points. Framework (sensors, network, dispatchers), DataBackend (server side + channel), MessageDispatcher.createAggregationChannel / getAllAggregationChannel, events (NETWORK_PRECONNECT / NETWORK_DISCONNECT), org.lifesocial.utilities.ConfigLoader (combineParameter, monitorDataVisual, monitoringTo*, autoStartMonitoring), org.eclipse.osgi.framework.console (commands), org.eclipse.ui (plugin.xml handlers), webprovider (REST/JSON), tester (automated start/stop), SQLite JDBC and gnuplot.

Evolution and supersession