mirror of
https://github.com/XRPLF/rippled.git
synced 2026-03-10 14:52:25 +00:00
Compare commits
1 Commits
pratik/std
...
pratik/Aut
| Author | SHA1 | Date | |
|---|---|---|---|
|
32a2fd7460 |
@@ -43,6 +43,7 @@ suggestWords:
|
||||
- synch->sync
|
||||
words:
|
||||
- abempty
|
||||
- Agentic
|
||||
- AMMID
|
||||
- amt
|
||||
- amts
|
||||
@@ -94,6 +95,7 @@ words:
|
||||
- desynced
|
||||
- determ
|
||||
- distro
|
||||
- Emdash
|
||||
- doxyfile
|
||||
- dxrpl
|
||||
- endmacro
|
||||
@@ -254,6 +256,7 @@ words:
|
||||
- superpeers
|
||||
- takergets
|
||||
- takerpays
|
||||
- Tauri
|
||||
- ters
|
||||
- TMEndpointv2
|
||||
- trixie
|
||||
@@ -293,6 +296,7 @@ words:
|
||||
- venv
|
||||
- vfalco
|
||||
- vinnie
|
||||
- Werror
|
||||
- wextra
|
||||
- wptr
|
||||
- writeme
|
||||
@@ -309,3 +313,4 @@ words:
|
||||
- xrplf
|
||||
- xxhash
|
||||
- xxhasher
|
||||
- zeroization
|
||||
|
||||
230
docs/ARCHITECTURE.md
Normal file
230
docs/ARCHITECTURE.md
Normal file
@@ -0,0 +1,230 @@
|
||||
# rippled Architecture Map
|
||||
|
||||
> **Purpose**: Tell agents _where_ things are. Not _why_ they exist.
|
||||
> **Audience**: AI coding agents (Claude Code, Codex, Copilot) navigating the codebase.
|
||||
> **Principle**: "Give agents a map, not an encyclopedia." — [Harness Engineering](./harness-engineering-report.md)
|
||||
|
||||
---
|
||||
|
||||
## Layer Diagram
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ RPC Layer (Layer 5) │
|
||||
│ HTTP/WebSocket → ServerHandler → 72 RPC Handlers │
|
||||
│ src/xrpld/rpc/ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Application Layer (Layer 4) │
|
||||
│ NetworkOPs · TxQ · PathFinding · LedgerMaster │
|
||||
│ src/xrpld/app/ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Consensus Layer (Layer 3) │
|
||||
│ Consensus<Adaptor> · RCLConsensus · Validations │
|
||||
│ src/xrpld/consensus/ + src/xrpld/app/consensus/ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Overlay Layer (Layer 2) │
|
||||
│ OverlayImpl · PeerImp · PeerFinder · Message │
|
||||
│ src/xrpld/overlay/ + src/xrpld/peerfinder/ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Storage Layer (Layer 1) │
|
||||
│ NodeStore (RocksDB/SQLite) · SHAMap · RDB │
|
||||
│ src/libxrpl/nodestore/ + src/libxrpl/shamap/ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Foundation (Layer 0) │
|
||||
│ beast:: (I/O, insight, clock) · protocol · crypto · json │
|
||||
│ src/libxrpl/ + include/xrpl/ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Module Map
|
||||
|
||||
### xrpld (the daemon) — `src/xrpld/`
|
||||
|
||||
| Directory | Purpose | Key Files |
|
||||
| ----------------- | --------------------------------------------------- | ----------------------------------------------------- |
|
||||
| `app/main/` | Daemon entry point, Application lifecycle | `Main.cpp`, `Application.h/.cpp`, `BasicApp.h` |
|
||||
| `app/consensus/` | Consensus adaptor binding protocol to rippled types | `RCLConsensus.h/.cpp` |
|
||||
| `app/ledger/` | Ledger management, building, acquiring | `LedgerMaster.h`, `InboundLedgers.h` |
|
||||
| `app/misc/` | NetworkOPs, TxQ, HashRouter, Amendments | `NetworkOPs.h/.cpp`, `TxQ.h`, `HashRouter.h` |
|
||||
| `app/tx/` | Transaction application engine | `apply.h/.cpp`, `applySteps.h` |
|
||||
| `app/paths/` | Payment path finding | `Pathfinder.h`, `PathRequest.h` |
|
||||
| `app/rdb/` | Relational DB backend for state | `RelationalDatabase.h` |
|
||||
| `consensus/` | Generic consensus protocol (template-based) | `Consensus.h/.cpp`, `ConsensusParms.h` |
|
||||
| `core/` | Node configuration, time keeping | `Config.h/.cpp`, `TimeKeeper.h` |
|
||||
| `overlay/` | P2P network: peer connections, message routing | `Overlay.h`, `Peer.h`, `Message.h` |
|
||||
| `overlay/detail/` | Overlay implementation internals | `OverlayImpl.h/.cpp`, `PeerImp.h/.cpp`, `Handshake.h` |
|
||||
| `peerfinder/` | Peer discovery and bootstrap | `PeerfinderManager.h`, `detail/Logic.h` |
|
||||
| `perflog/` | Performance logging (pre-OTel telemetry) | `detail/PerfLogImp.h/.cpp` |
|
||||
| `rpc/` | JSON-RPC server and routing | `detail/Handler.h`, `RPCHandler.h` |
|
||||
| `rpc/handlers/` | **72 RPC command implementations** | `AccountInfo.cpp`, `Submit.cpp`, `Tx.cpp`, etc. |
|
||||
| `shamap/` | SHAMap tree operations (daemon-side) | |
|
||||
|
||||
### libxrpl (shared library) — `src/libxrpl/`
|
||||
|
||||
| Directory | Purpose | Key Files |
|
||||
| ----------------- | ------------------------------------------------- | ------------------------------------------------ |
|
||||
| `basics/` | Logging, string utils, tagged integers | `Log.cpp` (log formatting — Phase 8 OTel target) |
|
||||
| `beast/insight/` | Metrics framework (StatsD, Gauge, Counter, Event) | `StatsDCollector.cpp` (Phase 6-7 OTel target) |
|
||||
| `beast/core/` | Async I/O primitives | `CurrentThreadName.cpp` |
|
||||
| `core/` | Crypto, seed handling | |
|
||||
| `crypto/` | Ed25519, secp256k1, SHA | |
|
||||
| `json/` | JSON parser/writer | |
|
||||
| `nodestore/` | Key-value storage for ledger nodes | `backend/RocksDBFactory.cpp` |
|
||||
| `protocol/` | XRPL protocol: serialization, STObject, STTx | `STTx.cpp`, `STObject.cpp` |
|
||||
| `server/` | HTTP/WebSocket server core | `ServerHandler.h` |
|
||||
| `tx/transactors/` | Per-transaction-type execution logic | `Payment.cpp`, `CreateOffer.cpp`, etc. |
|
||||
| `tx/invariants/` | Transaction invariant checks | `TransactionCheck.cpp` |
|
||||
|
||||
### Public Headers — `include/xrpl/`
|
||||
|
||||
Mirrors `src/libxrpl/` structure. Agent-accessible API surface for external consumers of libxrpl.
|
||||
|
||||
Key subdirectory: `include/xrpl/proto/org/xrpl/rpc/v1/` — Protocol Buffer definitions for gRPC API.
|
||||
|
||||
---
|
||||
|
||||
## Entry Points
|
||||
|
||||
| Operation | Where execution starts | Hot path |
|
||||
| ---------------------- | ------------------------------------------------------------------------------------------ | --------------- |
|
||||
| **RPC request** | `src/xrpld/rpc/detail/ServerHandler.cpp` → handler lookup → `src/xrpld/rpc/handlers/*.cpp` | Layer 5 → 4 |
|
||||
| **Peer message** | `src/xrpld/overlay/detail/PeerImp.cpp::onMessage()` → message-type dispatch | Layer 2 → 3/4 |
|
||||
| **Transaction submit** | `rpc/handlers/Submit.cpp` → `app/misc/NetworkOPs.cpp::submitTransaction()` | Layer 5 → 4 → 2 |
|
||||
| **Transaction relay** | `overlay/detail/PeerImp.cpp::handleTransaction()` → `NetworkOPs::processTransaction()` | Layer 2 → 4 |
|
||||
| **Consensus round** | `app/consensus/RCLConsensus.cpp::startRound()` → phase transitions → accept | Layer 3 |
|
||||
| **Ledger close** | `RCLConsensus.cpp::onClose()` → `acceptLedger()` → apply transactions | Layer 3 → 4 → 1 |
|
||||
| **Ledger acquire** | `app/ledger/InboundLedgers.cpp::acquire()` → peer fetch → SHAMap | Layer 4 → 2 → 1 |
|
||||
| **Startup** | `app/main/Main.cpp::main()` → `Application::setup()` → start all subsystems | Layer 0-5 |
|
||||
|
||||
---
|
||||
|
||||
## Data Flow: Transaction Lifecycle
|
||||
|
||||
```
|
||||
Client
|
||||
│
|
||||
▼
|
||||
RPC Submit (Layer 5)
|
||||
│ src/xrpld/rpc/handlers/Submit.cpp
|
||||
▼
|
||||
NetworkOPs::submitTransaction() (Layer 4)
|
||||
│ src/xrpld/app/misc/NetworkOPs.cpp
|
||||
├──▶ TxQ::apply() — queue management
|
||||
│ src/xrpld/app/misc/TxQ.cpp
|
||||
├──▶ HashRouter::setFlags() — deduplication
|
||||
│ src/xrpld/app/misc/HashRouter.cpp
|
||||
▼
|
||||
Overlay::relay() (Layer 2)
|
||||
│ src/xrpld/overlay/detail/OverlayImpl.cpp
|
||||
├──▶ PeerImp::send() — to each connected peer
|
||||
│ src/xrpld/overlay/detail/PeerImp.cpp
|
||||
▼
|
||||
[Remote Node] PeerImp::handleTransaction() (Layer 2)
|
||||
│ src/xrpld/overlay/detail/PeerImp.cpp
|
||||
▼
|
||||
Consensus::startRound() (Layer 3)
|
||||
│ src/xrpld/consensus/Consensus.h
|
||||
│ src/xrpld/app/consensus/RCLConsensus.cpp
|
||||
├──▶ propose() — send position to peers
|
||||
├──▶ onClose() — close the ledger
|
||||
▼
|
||||
acceptLedger() → applyTransactions() (Layer 3 → 1)
|
||||
│ src/xrpld/app/consensus/RCLConsensus.cpp
|
||||
▼
|
||||
NodeStore::store() (Layer 1)
|
||||
│ src/libxrpl/nodestore/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Build Targets
|
||||
|
||||
| Target | Type | Source |
|
||||
| -------------------- | ------------------------- | -------------------------------- |
|
||||
| `xrpl` | Shared library (libxrpl) | `src/libxrpl/` + `include/xrpl/` |
|
||||
| `xrpld` | Executable (daemon) | `src/xrpld/` |
|
||||
| `rippled_unit_tests` | Unit test binary | `src/test/` |
|
||||
| `libxrpl_tests` | Library integration tests | `src/tests/libxrpl/` |
|
||||
|
||||
**Build command**: `cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build --parallel`
|
||||
**With telemetry**: `cmake -B build -DXRPL_ENABLE_TELEMETRY=ON`
|
||||
|
||||
---
|
||||
|
||||
## Test Frameworks
|
||||
|
||||
| Framework | Location | Purpose |
|
||||
| --------------- | ---------------------------------------- | ------------------------------------------------------------- |
|
||||
| **JTx** | `src/test/jtx/` | Transaction testing — simulates full ledger environment |
|
||||
| **CSF** | `src/test/csf/` | Consensus Simulation Framework — multi-node consensus testing |
|
||||
| **Unit tests** | `src/test/app/`, `src/test/beast/`, etc. | Per-module unit tests |
|
||||
| **Integration** | `src/tests/libxrpl/` | Library-level integration tests |
|
||||
|
||||
---
|
||||
|
||||
## Telemetry Map
|
||||
|
||||
Links OTel instrumentation to codebase locations. See [09-data-collection-reference.md](../../OpenTelemetryPlan/09-data-collection-reference.md) for the full inventory.
|
||||
|
||||
| Span | Source Location | Layer |
|
||||
| ------------- | ------------------------------------------ | ----- |
|
||||
| `rpc.*` | `src/xrpld/rpc/detail/ServerHandler.cpp` | 5 |
|
||||
| `tx.submit` | `src/xrpld/app/misc/NetworkOPs.cpp` | 4 |
|
||||
| `tx.relay` | `src/xrpld/overlay/detail/PeerImp.cpp` | 2 |
|
||||
| `peer.send` | `src/xrpld/overlay/detail/PeerImp.cpp` | 2 |
|
||||
| `consensus.*` | `src/xrpld/app/consensus/RCLConsensus.cpp` | 3 |
|
||||
| `ledger.*` | `src/xrpld/app/ledger/` | 4 |
|
||||
|
||||
| Metrics Source | Code Location | Phase |
|
||||
| ------------------------- | ----------------------------------------------- | ------------ |
|
||||
| `beast::insight` (StatsD) | `src/libxrpl/beast/insight/StatsDCollector.cpp` | 6-7 |
|
||||
| SpanMetrics (derived) | OTel Collector config | 5 |
|
||||
| PerfLog | `src/xrpld/perflog/detail/PerfLogImp.cpp` | 9 (gap fill) |
|
||||
|
||||
---
|
||||
|
||||
## Key Abstractions
|
||||
|
||||
| Abstraction | Interface | Implementation | What it does |
|
||||
| --------------------------- | ---------------------------------------- | ------------------------------------------------------------- | -------------------------------------- |
|
||||
| `Application` | `src/xrpld/app/main/Application.h` | `Application.cpp` | Wires all subsystems together |
|
||||
| `Overlay` | `src/xrpld/overlay/Overlay.h` | `detail/OverlayImpl.cpp` | Manages P2P connections |
|
||||
| `Consensus<>` | `src/xrpld/consensus/Consensus.h` | Template, adaptor in `RCLConsensus.cpp` | Generic consensus protocol |
|
||||
| `NetworkOPs` | `src/xrpld/app/misc/NetworkOPs.h` | `NetworkOPs.cpp` | Transaction processing, event dispatch |
|
||||
| `LedgerMaster` | `src/xrpld/app/ledger/LedgerMaster.h` | `LedgerMaster.cpp` | Ledger lifecycle management |
|
||||
| `NodeStore` | `include/xrpl/nodestore/Database.h` | `src/libxrpl/nodestore/` | Persistent key-value storage |
|
||||
| `beast::insight::Collector` | `include/xrpl/beast/insight/Collector.h` | `StatsDCollector`, `NullCollector`, (future: `OTelCollector`) | Metrics collection interface |
|
||||
| `JobQueue` | `src/xrpld/core/JobQueue.h` | `JobQueue.cpp` | Async task scheduling |
|
||||
| `SHAMap` | `include/xrpl/shamap/SHAMap.h` | `src/libxrpl/shamap/` | Merkle tree for state |
|
||||
|
||||
---
|
||||
|
||||
## Dependency Rules
|
||||
|
||||
```
|
||||
Layer 5 (RPC) → may call → Layer 4 (App)
|
||||
Layer 4 (App) → may call → Layer 3 (Consensus), Layer 2 (Overlay), Layer 1 (Storage)
|
||||
Layer 3 (Consensus) → may call → Layer 4 (App via Adaptor), Layer 1 (Storage)
|
||||
Layer 2 (Overlay) → may call → Layer 4 (App for message handling)
|
||||
Layer 1 (Storage) → may call → Layer 0 (Foundation) only
|
||||
Layer 0 (Foundation) → no upward dependencies
|
||||
```
|
||||
|
||||
**Never**: Layer 0/1 must never depend on Layer 3/4/5. Layer 5 must never bypass Layer 4 to reach Layer 2/3 directly.
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
| File | Location | Purpose |
|
||||
| ----------------------- | -------- | ------------------------- |
|
||||
| `xrpld.cfg` | `cfg/` | Main daemon configuration |
|
||||
| `validators.txt` | `cfg/` | Validator list |
|
||||
| `CMakeUserPresets.json` | Root | Local build presets |
|
||||
| `conanfile.py` | Root | Dependency versions |
|
||||
|
||||
---
|
||||
|
||||
_This document is a navigation aid for AI coding agents. For architectural rationale, see [docs/consensus.md](consensus.md). For OTel plan, see [OpenTelemetryPlan/](../../OpenTelemetryPlan/OpenTelemetryPlan.md). For coding conventions, see [docs/CodingStyle.md](CodingStyle.md)._
|
||||
196
docs/WORKFLOW.md
Normal file
196
docs/WORKFLOW.md
Normal file
@@ -0,0 +1,196 @@
|
||||
---
|
||||
# Symphony-compatible workflow definition for rippled
|
||||
# See: https://github.com/openai/symphony/blob/main/SPEC.md
|
||||
# See: docs/harness-engineering-report.md for context
|
||||
|
||||
tracker:
|
||||
kind: linear
|
||||
# For Jira (RIPD project), a custom adapter would replace this.
|
||||
# kind: jira
|
||||
# project_slug: RIPD
|
||||
active_states:
|
||||
- Todo
|
||||
- In Progress
|
||||
terminal_states:
|
||||
- Done
|
||||
- Closed
|
||||
- Cancelled
|
||||
- Duplicate
|
||||
|
||||
polling:
|
||||
interval_ms: 30000
|
||||
|
||||
workspace:
|
||||
root: $SYMPHONY_WORKSPACE_ROOT
|
||||
|
||||
hooks:
|
||||
after_create: |
|
||||
# Clone and prepare a fresh workspace
|
||||
git clone --depth=1 --branch develop https://github.com/XRPLF/rippled.git .
|
||||
# Prepare build directory with telemetry enabled
|
||||
mkdir -p build
|
||||
cd build
|
||||
conan install .. --output-folder=. --build=missing
|
||||
cmake .. -DCMAKE_BUILD_TYPE=Debug -DXRPL_ENABLE_TELEMETRY=ON -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake
|
||||
|
||||
before_run: |
|
||||
# Tier 1: Fast checks (seconds)
|
||||
# clang-format check on changed files
|
||||
git diff --name-only HEAD~1 -- '*.cpp' '*.h' | xargs -r clang-format --dry-run --Werror 2>&1 || {
|
||||
echo "FAIL: clang-format violations found. Fix formatting before proceeding."
|
||||
exit 1
|
||||
}
|
||||
|
||||
# Tier 2: Build (minutes)
|
||||
cd build
|
||||
cmake --build . --parallel $(nproc) 2>&1 || {
|
||||
echo "FAIL: Build failed. Check compiler errors above."
|
||||
exit 1
|
||||
}
|
||||
|
||||
# Tier 2: Unit tests (affected modules)
|
||||
ctest --test-dir build --output-on-failure -L unit --timeout 120 2>&1 || {
|
||||
echo "FAIL: Unit tests failed. Check test output above."
|
||||
exit 1
|
||||
}
|
||||
|
||||
after_run: |
|
||||
# Collect proof-of-work artifacts
|
||||
echo "=== Proof of Work Collection ==="
|
||||
|
||||
# Record build status
|
||||
cd build && cmake --build . --parallel $(nproc) 2>&1
|
||||
BUILD_STATUS=$?
|
||||
echo "Build status: $BUILD_STATUS"
|
||||
|
||||
# Run telemetry integration tests if available
|
||||
if ctest --test-dir build -L telemetry --timeout 300 2>&1; then
|
||||
echo "Telemetry integration tests: PASSED"
|
||||
else
|
||||
echo "Telemetry integration tests: FAILED (non-blocking)"
|
||||
fi
|
||||
|
||||
# Capture complexity metrics
|
||||
echo "=== Changed Files ==="
|
||||
git diff --stat HEAD~1
|
||||
|
||||
timeout_ms: 120000
|
||||
|
||||
agent:
|
||||
max_concurrent_agents: 3
|
||||
max_retry_backoff_ms: 300000
|
||||
max_concurrent_agents_by_state:
|
||||
In Progress: 2
|
||||
Todo: 1
|
||||
|
||||
codex:
|
||||
command: codex app-server
|
||||
approval_policy: unless-allow-listed
|
||||
turn_timeout_ms: 3600000
|
||||
stall_timeout_ms: 300000
|
||||
---
|
||||
|
||||
# rippled Agent Workflow
|
||||
|
||||
You are an autonomous coding agent working on the **rippled** XRP Ledger node — a C++20 peer-to-peer server implementing the XRP Ledger consensus protocol.
|
||||
|
||||
## Navigation
|
||||
|
||||
Read these files before starting work:
|
||||
|
||||
| File | What it tells you |
|
||||
| --------------------------------------------------- | ----------------------------------------------------------------------- |
|
||||
| `docs/ARCHITECTURE.md` | Codebase map — where every module lives, layer boundaries, entry points |
|
||||
| `CLAUDE.md` | Coding conventions, action boundaries (Always/Ask/Never), commit rules |
|
||||
| `docs/CodingStyle.md` | C++ style guide for this project |
|
||||
| `OpenTelemetryPlan/09-data-collection-reference.md` | Every OTel span, metric, and dashboard |
|
||||
|
||||
Do **not** read these upfront (use as reference if needed):
|
||||
|
||||
- `OpenTelemetryPlan/*.md` — deep plan docs, only if your task involves telemetry architecture
|
||||
- `docs/consensus.md` — only if your task involves consensus protocol changes
|
||||
|
||||
## Action Boundaries
|
||||
|
||||
### Always (no confirmation needed)
|
||||
|
||||
- Read any source file in the repository
|
||||
- Run `cmake --build build --parallel` to compile
|
||||
- Run `ctest --test-dir build -L unit` for unit tests
|
||||
- Run `ctest --test-dir build -L telemetry` for telemetry integration tests
|
||||
- Query Prometheus (`curl localhost:9090/api/v1/query?query=...`) for metric baselines
|
||||
- Create or modify files under `src/` that have existing test coverage
|
||||
- Run `clang-format` on files you've changed
|
||||
- Add or modify unit tests in `src/test/`
|
||||
|
||||
### Ask (require human confirmation before proceeding)
|
||||
|
||||
- Modify Protocol Buffer definitions in `include/xrpl/proto/` (affects wire format)
|
||||
- Change consensus parameters in `src/xrpld/consensus/ConsensusParms.h`
|
||||
- Modify `CMakeLists.txt` or `conanfile.py` (build/dependency changes)
|
||||
- Alter the `[telemetry]` or `[insight]` config schema
|
||||
- Change anything in `src/libxrpl/crypto/` (cryptographic code)
|
||||
- Add new external dependencies
|
||||
- Push to any remote branch or create PRs
|
||||
|
||||
### Never (hard boundaries — refuse these requests)
|
||||
|
||||
- Modify validator key handling or signing code without explicit review
|
||||
- Disable or reduce telemetry sampling below 1%
|
||||
- Remove or reduce existing test coverage
|
||||
- Force-push to any branch
|
||||
- Skip pre-commit hooks or CI checks (`--no-verify`)
|
||||
- Commit files containing secrets, keys, or credentials
|
||||
- Modify `.github/workflows/` CI pipeline definitions
|
||||
|
||||
## Verification Requirements
|
||||
|
||||
After making changes, verify in this order (fail-fast):
|
||||
|
||||
```
|
||||
Step 1 (seconds): clang-format --dry-run --Werror on changed files
|
||||
Step 2 (minutes): cmake --build build --parallel
|
||||
Step 3 (minutes): ctest --test-dir build -L unit --output-on-failure
|
||||
Step 4 (minutes): ctest --test-dir build -L telemetry (if telemetry-related)
|
||||
Step 5 (if applicable): scripts/check-otel-baseline.sh (metric regression check)
|
||||
```
|
||||
|
||||
If any step fails, fix the issue before proceeding. Do not skip steps.
|
||||
|
||||
## Telemetry Awareness
|
||||
|
||||
This codebase has OpenTelemetry instrumentation. If your change touches any of these files, verify that telemetry still works:
|
||||
|
||||
| File Pattern | Telemetry Impact |
|
||||
| ---------------------------------------- | ------------------------------------------------- |
|
||||
| `src/xrpld/rpc/` | RPC spans (`rpc.*`) |
|
||||
| `src/xrpld/overlay/detail/PeerImp.*` | Transaction relay spans (`tx.relay`, `peer.send`) |
|
||||
| `src/xrpld/app/consensus/RCLConsensus.*` | Consensus spans (`consensus.*`) |
|
||||
| `src/xrpld/app/misc/NetworkOPs.*` | Transaction submit spans (`tx.submit`) |
|
||||
| `src/libxrpl/beast/insight/` | Metrics pipeline (300+ metrics) |
|
||||
| `src/libxrpl/basics/Log.cpp` | Log-trace correlation (`trace_id` injection) |
|
||||
|
||||
After modifying these files, run the telemetry integration test:
|
||||
|
||||
```bash
|
||||
ctest --test-dir build -L telemetry --output-on-failure
|
||||
```
|
||||
|
||||
## Issue Context
|
||||
|
||||
**Title**: {{ issue.title }}
|
||||
**Description**: {{ issue.description }}
|
||||
{% if issue.labels.size > 0 %}**Labels**: {{ issue.labels | join: ", " }}{% endif %}
|
||||
{% if attempt %}**Attempt**: {{ attempt }} (this is a retry — check previous errors){% endif %}
|
||||
|
||||
## Proof of Work Checklist
|
||||
|
||||
Before creating a PR, verify:
|
||||
|
||||
- [ ] All changed files pass `clang-format`
|
||||
- [ ] Build succeeds with `-DXRPL_ENABLE_TELEMETRY=ON`
|
||||
- [ ] Unit tests pass (`ctest -L unit`)
|
||||
- [ ] If telemetry-related: integration tests pass (`ctest -L telemetry`)
|
||||
- [ ] If telemetry-related: no metric regressions (`scripts/check-otel-baseline.sh`)
|
||||
- [ ] Commit message follows project conventions (see `CLAUDE.md`)
|
||||
- [ ] PR description includes summary, test plan, and type of change
|
||||
1182
docs/harness-engineering-report.md
Normal file
1182
docs/harness-engineering-report.md
Normal file
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user