stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
108d1c64b323808d6085fca05818fc581c6b003a
git.stella-ops.org/docs/modules/graph/packaging.md
StellaOps Bot 48702191be
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
feat(graph-api): Add schema review notes for upcoming Graph API changes 
feat(sbomservice): Add placeholder for SHA256SUMS in LNM v1 fixtures

docs(devportal): Create README for SDK archives in public directory

build(devportal): Implement offline bundle build script

test(devportal): Add link checker script for validating links in documentation

test(devportal): Create performance check script for dist folder size

test(devportal): Implement accessibility check script using Playwright and Axe

docs(devportal): Add SDK quickstart guide with examples for Node.js, Python, and cURL

feat(excititor): Implement MongoDB storage for airgap import records

test(findings): Add unit tests for export filters hash determinism

feat(findings): Define attestation contracts for ledger web service

feat(graph): Add MongoDB options and service collection extensions for graph indexing

test(graph): Implement integration tests for MongoDB provider and service collection extensions

feat(zastava): Define configuration options for Zastava surface secrets

build(tests): Create script to run Concelier linkset tests with TRX output
2025-11-22 19:22:30 +02:00

2.8 KiB
Raw Blame History

Graph Indexer packaging (Runtime & Signals 140.A)

Deployment overlays

  • Helm/Compose should expose two timers for analytics: GRAPH_ANALYTICS_CLUSTER_INTERVAL and GRAPH_ANALYTICS_CENTRALITY_INTERVAL (ISO-8601 duration, default 5m). Map to GraphAnalyticsOptions.
  • Change-stream/backfill worker toggles via GRAPH_CHANGE_POLL_INTERVAL, GRAPH_BACKFILL_INTERVAL, GRAPH_CHANGE_MAX_RETRIES, GRAPH_CHANGE_RETRY_BACKOFF.
  • Mongo bindings (optional): GRAPH_CHANGE_COLLECTION, GRAPH_CHANGE_SEQUENCE_FIELD, GRAPH_CHANGE_NODE_FIELD, GRAPH_CHANGE_EDGE_FIELD, GRAPH_CHANGE_IDEMPOTENCY_COLLECTION, GRAPH_ANALYTICS_SNAPSHOT_COLLECTION, GRAPH_ANALYTICS_PROGRESS_COLLECTION.
  • Mongo connection: STELLAOPS_GRAPH_MONGO_CONNECTION and STELLAOPS_GRAPH_MONGO_DB feed AddGraphMongoDatabase for clients/services.
  • New Mongo collections:
    • graph_cluster_overlays — cluster assignments (tenant, snapshot_id, node_id, cluster_id, generated_at).
    • graph_centrality_overlays — degree + betweenness approximations per node.
    • optional node updates write attributes.cluster_id when WriteClusterAssignmentsToNodes=true.

Offline kit alignment

  • Cluster/centrality overlays are exportable alongside nodes.jsonl/edges.jsonl; keep under artifacts/graph-snapshots/{snapshotId}/overlays/ for air-gapped imports.
  • Seed bundle layout:
    • clusters.ndjson — overlay records (one per node) matching graph_cluster_overlays schema.
    • centrality.ndjson — overlay records with degree/betweenness.
    • manifest.json — references snapshot manifest hash and run timestamps.
  • Determinism: overlays ordered by node_id (ordinal) to keep bundle hashes stable.

Observability hooks

  • Metrics (Meter StellaOps.Graph.Indexer):
    • graph_analytics_runs_total, graph_analytics_failures_total, graph_analytics_duration_seconds, graph_analytics_clusters_total, graph_analytics_centrality_total.
    • graph_changes_total, graph_backfill_total, graph_change_failures_total, graph_change_lag_seconds.
  • Recommended alerts: lag > 5m, failures > 0 over 10m window, cluster job duration > 2m.

Configuration defaults

  • Cluster/centrality intervals: 5 minutes; label-propagation iterations: 6; betweenness sample size: 12.
  • Change stream: poll every 5s, backfill every 15m, max retries 3 with 3s backoff, batch size 256.
  • Overlay exports: clusters/centrality written to overlays/clusters.ndjson and overlays/centrality.ndjson with manifest; ordered by node_id for deterministic bundle hashes.

Notes

  • Analytics writes are idempotent (upserts keyed on tenant+snapshot+node_id). Change-stream processing is idempotent via sequence tokens persisted in IIdempotencyStore (Mongo or in-memory for tests).
  • Keep Helm/Compose values in sync with these defaults when publishing the Runtime & Signals 140.A bundle.