docs/alpha-preview.md

# HertzBeat Community Alpha Preview

This document is for the GitHub community alpha preview branch. It is not a
stable Apache HertzBeat release checklist. Use it to try the new entity-centered
observability and Vite React frontend, report issues, and help harden the project
toward a beta.

## What Is In Scope

- Entity-centered observability read models for metrics, logs, traces, topology,
  alerts, owners, runbooks, and handoff context.
- Vite React `web-app` workflows for the operational shell, entity management,
  topology, instrumentation, and the three-signal query workspace.
- OTLP trace/log/metric query paths backed by the existing warehouse and
  Greptime integrations.
- Local demo topology relation seeding for the small Checkout API -> Payment API
  -> Orders DB example when the `local` Spring profile is active.

## Local Source Quickstart

Use Java 25, Node.js 22 and pnpm 10. Build the production frontend before a
source release package; a development server is not release evidence. See the
[installation guide](../home/docs/start/package-deploy.md) for first-run Setup
and the [upgrade guide](../home/docs/start/upgrade.md) before reusing data.

1. Start the backend from `hertzbeat-startup` with Java 25.

   Keep the Arrow JVM open option when running locally:

   ```shell
   --add-opens=java.base/java.nio=ALL-UNNAMED
   ```

   The local backend listens on `http://127.0.0.1:1157` by default.

2. Start the Vite React frontend:

   ```shell
   cd web-app
   corepack pnpm@10.9.0 install --frozen-lockfile
   corepack pnpm@10.9.0 dev
   ```

   The preview frontend listens on `http://127.0.0.1:4200`.

3. Open `http://127.0.0.1:4200`. For a fresh installation, complete Setup using
   the installation-local unlock credential and create an administrator. For an
   existing installation, use its configured account. Do not assume a built-in
   default password. Keep Setup credentials and tokens out of issue reports.

See the [Explore and saved-query guide](../home/docs/help/explore_saved_queries.md)
for three-signal query, recovery, Live, sharing and conflict workflows, and the
[Dashboard guide](../home/docs/help/perses_dashboard.md) for the supported document
subset. These describe alpha capabilities, not full parity with another product.

## Alpha Validation Checklist

Before opening an alpha issue or pull request, run the smallest check that
matches the area you changed.

Backend entity, topology, observability, and Greptime query changes:

```shell
./mvnw -pl hertzbeat-manager,hertzbeat-observability,hertzbeat-warehouse \
  -Dtest=EntityDetailObservabilityReadModelServiceTest,EntityTopologyQueryServiceTest,EntityWorkspaceAccessServiceTest,EntityWorkspaceQueryServiceTest,TraceCallTopologyQueryServiceTest,LocalTopologyDemoRelationSeederTest,LogQueryControllerTest,EntityObservabilityGatewayImplTest,EntityTraceQueryServiceImplTest,GreptimeTraceQueryRepositoryTest,GreptimeDbDataStorageTest \
  test -DskipITs -Dsurefire.failIfNoSpecifiedTests=false -DfailIfNoTests=false
```

Startup source package proof:

```shell
./mvnw -pl hertzbeat-startup -am -Prelease -DskipTests package
```

Topology, entity, observability, shell, session, and shared UI changes:

```shell
cd web-app
corepack pnpm@10.9.0 test -- \
  src/features/entity src/features/topology src/features/instrumentation \
  src/features/explore
```

Complete frontend release gate:

```shell
cd web-app
corepack pnpm@10.9.0 verify
```

Visible changes also require a production build, a real backend, and a Browser
check of the affected workflow. Do not use mocked topology or signal data as
release evidence.

## Delivered Operator Workflows

The alpha uses Greptime's query organization, Perses' document model and mature
APM service drilldowns as design references. It does not claim feature parity
with those products, SigNoz, SkyWalking or Datadog.

- **First use:** distinguish Agentless target monitoring from application OTLP
  instrumentation. The intake catalog declares each recipe's signal support.
  The real reference paths are an Agentless MySQL target and an application
  using the official OpenTelemetry Java agent. Other catalog entries are not
  automatically covered by this acceptance.
- **Daily entry:** Start links to real monitors, unresolved alerts, registered
  services and saved queries. Each query reports its own loading, empty or
  failure state; an empty Entity catalog does not establish that no telemetry
  exists.
- **Explore:** metrics, logs and traces share service, namespace, environment,
  filters and a fixed absolute investigation window when navigating. Trace
  newest/duration sorting runs before pagination. Coverage identifies a complete
  query window or a bounded fallback; missing or ambiguous roots have unknown
  root duration and sort after valid durations. Live data can change between
  requests; pagination is not a snapshot isolation guarantee.
  Query controls sit above the results, with log/trace filters in a companion
  column. A collapsible **Workflow guide** explains each signal’s query and
  inspection steps. Metrics keep an inspectable catalog and chart/sample-table
  switch; selecting a metric changes the draft until **Query** is applied.
  A base metric query names one stored metric; a typed composition can combine
  up to four source queries and four bounded arithmetic formulas. Supported
  controls include aggregation, grouping, label filters, rate/increase/delta,
  fixed time shifts, rollup and nested time aggregation, not arbitrary PromQL.
  Aggregation preserves protected service and entity scope. Count means
  contributing series, not requests. Histogram bucket queries retain `le`;
  bucket values are not latency percentiles. Invalid filter clauses or grouping
  labels fail rather than silently widening the query. The trend precedes the
  sampled summary; concise legends do not remove complete labels from it.
  Apply a draft with **Query**; open a result to inspect its evidence and
  use **Back to results** to retain the original time window and filters.
  Log severity categories use the OTel numeric bands (for example Error is
  17–20 and includes Java `SEVERE`). **Original severity text** remains an
  independent exact filter; both conditions combine with AND. Category-filtered
  queries can be saved and reopened, but the restricted Dashboard and AI
  handoff contracts currently reject that filter rather than omit it.
  Historical Logs also offer bounded Patterns, identity-based Transactions and
  sampled calculated fields. Their disclosed sample or identity boundary is
  part of the result; a sampled calculation is not a full-window aggregate.
  Traces offer a typed two-span structural query plus bounded structural
  Patterns and a source-backed Request Flow Map. The map does not infer missing
  parent spans or services, and a missing correlated log does not establish a
  request outcome.
- **Services:** registered service Entities provide source, environment, last
  observed Trace time, service-wide RED and observed root operations. Greptime
  Flow aggregates SERVER requests into minute buckets; P95 is approximate and
  can be unavailable, and sampling completeness is unknown. Ingestion audit
  counts are separate from business request RED. Existing registered relations
  and monitor-linked alerts are evidence, not complete inferred dependencies.
  An operation can lead to matching Traces and then associated Logs while
  retaining the investigation context. Direct service Logs do not imply an
  operation filter. The detail heading identifies the canonical service and
  environment; **Service information** exposes the catalog alias, source,
  historical freshness and bounded associations. Identity metadata can remain
  visible during refresh while signal values retain loading or failure states.
  The **Performance** directory compares observed requests, errors, error rate
  and P95 across matching services. Choose a window, optionally narrow by search
  or environment, run Query, then sort and open a service to inspect its trends
  and root operations. Both return actions preserve the directory view, filters,
  order, page and exact investigation window. **Registered** remains a separate
  metadata view when request evidence is unavailable.
  The server ranks all matching authorized services before pagination, bounded
  by 500 candidates and a 24-hour window. A larger scope requires narrower
  filters and returns no partial ranking. Missing observations remain unavailable
  values, not zero errors or healthy services; a storage failure returns no
  ranking. Catalog and telemetry reads do not share a snapshot, so late data can
  change order on refresh. This is not a health score, anomaly detector or
  complete resource catalog.
  Metrics API operation predicates match real metric labels
  and can correctly return no matching data.
- **Saved queries:** save applied conditions, reopen, update, save as and delete
  installation-shared assets under existing role permissions. Relative or exact
  time mode survives restart; reopening starts on the first page. The versioned
  query document is authoritative. Convertible legacy records open without an
  automatic write; unsupported records remain available for raw export.
- **Dashboards:** create, edit, copy, delete, import/export, adjust layout, save
  or cancel and add a panel from Explore. Standard Perses Dashboard JSON is
  accepted only within the HertzBeat subset: seven visual plugins, controlled query
  plugins, one Grid and service/namespace/environment variables. Metrics can use
  TimeSeries, Stat, Gauge or Table; the restricted Logs, Trace table and fixed
  Trace waterfall panels remain available. Panels load
  and fail independently. Shared runtime time and Explore return context remain
  explicit; fixed Trace waterfalls stay pinned when a service variable changes.
  Native revisions reject stale updates or deletes with HTTP 409. Cancel does
  not persist a draft. See the [Dashboard guide](../home/docs/help/perses_dashboard.md).
- **AI investigation:** bounded read-only tools, durable transcript replay,
  refusal, no-data, timeout, Stop/Retry and redaction are exercised with actual
  application data and a labeled local protocol provider. This establishes
  transport and policy behavior, not external model quality. See the
  [AI guide](../home/docs/help/ai_agent.md).

Service identity matching requires meaningful service-name or instance evidence;
namespace/environment alone cannot bind an unrelated service. Unresolved
identity does not prevent direct signal queries. The correction affects new
intake; previously stored identity attributes are not rewritten automatically.
Runtime dimensions such as Trace ID, operation and HTTP route are query context,
not new long-lived Entity identities.

The bounded intake check observes a fixed 120-second window. Previously received
signals are historical evidence, not continuing emitter liveness. Start a fresh
check after stopping an emitter, and inspect exporter authentication errors
separately. See the [instrumentation contract](instrumentation-api.md).

## Installation, Recovery and Acceptance Boundary

The local candidate was built from a frozen source snapshot with a fresh
production frontend and Java 25 startup package. Installed API and Browser
checks used the same archive. The reference environment covered H2, MySQL 8.4
and PostgreSQL 17 management persistence, separate GreptimeDB 1.1.4 telemetry,
restart, native metadata backup/restore, and a stopped single-node Greptime data
copy and restore. Preserve management data, telemetry, configuration and secrets
as separate backup responsibilities. This is not an online or distributed
backup guarantee. Do not copy a running database directory.

The real alert check raised MySQL connection count, observed firing notification
receipts, released the connections and observed recovery receipts. Repeated
firing notifications are possible; the proof does not establish exactly-once
delivery. AI protocol tests use a local controlled provider with explicit test
timeout/retry settings, not new product defaults.

Release evidence must record the source revision and uncommitted snapshot,
lockfiles, toolchain, archive digest, test commands and limits. Keep credentials,
runtime databases, screenshots and local evidence out of public commits. The
[release checklist](alpha-release-checklist.md) separates local acceptance from
publication. Source changes after an accepted archive require a new build and
appropriate revalidation.

## Local Scale Proof Data

Large topology scale proof data is not seeded by default. The local demo seeder
only creates the small demo relation repair during normal `local` profile
startup.

To explicitly seed the local mixed scale proof entity catalog, start the backend
with:

```shell
--hertzbeat.topology.local-scale-proof-seed=true
```

This is intended for local performance investigation only. Do not treat it as
required alpha setup.

## Known Alpha Limitations

- The Vite React frontend is still an alpha preview. Parity claims require
  route, action, API read/write, refresh, context-handoff, and Browser evidence.
- Background tabs suspend manager-event connections and reread current state
  when shown again; alert notification connections remain active. For many
  simultaneously open tabs, use an HTTP/2-capable HTTPS proxy: browser HTTP/1
  per-origin connection limits still apply to long-lived alert streams. See the
  [browser SSE connection limit](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events).
- Services do not yet provide a complete operation RED inventory, Apdex, a
  database/external-call product, causal root-cause analysis or complete inferred
  service dependencies. Trace duration distributions are deferred.
- Dashboard import/export is limited to the HertzBeat Perses subset. No
  standalone Perses service, arbitrary SQL, external data-source plugins, public
  sharing or plugin marketplace is included. Saved-query updates and deletes
  use revisions and reject stale writes; resolve conflicts or save a copy.
- Three-signal exploration does not provide Datadog's full query grammar,
  function and widget catalogs, prediction/anomaly algorithms, archive search,
  Watchdog/Findings, natural-language queries, public or scheduled dashboards,
  standalone resource pages, or direct metric-point-to-trace correlation.
  Patterns and calculated fields are bounded sampled views; structural Trace
  Patterns and Flow Map use a bounded observed-span population.
- Earlier alpha snapshots with a different V200 migration checksum require a
  fresh database for this preview. Do not repair the checksum or assume an
  automatic in-place upgrade. Historical PostgreSQL saved-query OID strings
  are not automatically converted into valid query documents.
- Topology large-graph behavior is optimized for inspection with render
  windows, table drilldown, and optional browser smoke. Continue filing cases
  where real data feels confusing or slow.
- Runtime verification may depend on local H2 or Greptime data shape. Greptime
  scale proof fixtures are local-only and should not be committed as generated
  proof artifacts.
- Source package rebuilds are expected to pass for the alpha candidate. If a
  local module or dependency warning blocks packaging, include the focused
  Maven command and output with the issue report.

## Reporting Issues

When filing alpha feedback, include:

- The route or API endpoint.
- The storage mode, for example H2-only or Greptime-backed traces.
- The browser viewport and whether the in-app refresh was used.
- Expected versus actual node, edge, table, or handoff behavior.
- Any focused test, Maven, Vitest, ESLint, or browser-smoke command that
  reproduces the issue.