durable-actors-observer 0.14.1 → 0.14.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +14 -0
- package/dist/InstanceTimeline.d.ts +45 -0
- package/dist/RequestObserver.d.ts +4 -3
- package/dist/RequestTimeline.d.ts +3 -1
- package/dist/ResidencyTimeline.d.ts +11 -0
- package/dist/SocketTimeline.d.ts +2 -3
- package/dist/client.d.ts +5 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +1212 -1187
- package/dist/observer-hooks.d.ts +1 -1
- package/dist/request-timeline.d.ts +10 -5
- package/dist/residency.d.ts +18 -0
- package/dist/standalone/app.css +1 -1
- package/dist/standalone/app.js +14 -14
- package/dist/styles.css +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -26,6 +26,8 @@ The package exports `ActorObserver`, `RequestObserver`, `Overview`, `WebSocketOb
|
|
|
26
26
|
|
|
27
27
|
Pass your own `ObserverClient` to connect these views to a hosted backend, or configure `HttpObserverClient` with your API prefix and fetch implementation. React remains a peer dependency. `ConsoleApp` provides the complete navigation shell and requires a `toggleTheme` callback; individual views can be placed inside your own navigation.
|
|
28
28
|
|
|
29
|
+
`Overview` shows a compact list of actor types below the runtime summary. Select a type to inspect its instances. The list has no metric columns, filters, or threshold legend.
|
|
30
|
+
|
|
29
31
|
Control-plane endpoints require a project in the path: `/v1/projects/{project_id}/observe/...`. The hosted backend should authorize access to that project and proxy the routes using its server-side admin credential. The CLI's `/api/observe` proxy uses its configured `DURABLE_ACTORS_PROJECT_ID`. Request traces include a required `projectId`; older stored traces without one are excluded from project results.
|
|
30
32
|
|
|
31
33
|
The observer version follows the SDK and runtime version. Run `bun run --bun release:prepare <version>` at the repository root before publishing a GitHub release. Release preflight checks all versions, and the workflow publishes the observer before the SDK. The SDK's `workspace:*` dependency becomes the exact observer version when packed.
|
|
@@ -38,10 +40,22 @@ The localhost-only `durable-actors dev` runtime allows observability requests wi
|
|
|
38
40
|
|
|
39
41
|
Use the Zoom slider to adjust the visible window smoothly from the full loaded history down to 1 ms, hold Ctrl or Command while scrolling over the waterfall to zoom around the cursor, or drag across the time axis to select a range. Scroll zoom keeps the slider synchronized and captures browser zoom only over the waterfall while the modifier key is held. Once zoomed, use the horizontal scrollbar beneath the requests, a horizontal trackpad gesture, or Shift+mouse-wheel to move through time. Operation labels stay in place. The slider supports arrow keys, Home, and End. Moving the slider fully left restores the full loaded history. The chosen window stays on the same timestamps as live calls arrive or older history loads. Only calls intersecting the window are shown; durations and queue timings still describe the full invocation.
|
|
40
42
|
|
|
43
|
+
Method rows stay in alphabetical order by actor type, instance, transport, and method. The inventory supplies published RPC methods, and the waterfall includes WebSocket callbacks even with zero calls. An inspected instance always shows all its methods. The global Requests view includes method rows only for instances represented in the loaded live or saved requests, so idle inventory does not add rows. Zooming and panning leave those rows in place. Custom clients can include optional `methods` names on each inventory actor; direct `RequestTimeline` embeds can supply `lanes` for methods without records. Without a deployment contract, rows cover observed operations.
|
|
44
|
+
|
|
41
45
|
Request details open in a right-side [shadcn Drawer](https://ui.shadcn.com/docs/components/radix/drawer), powered by Vaul. Dismiss with the close button, Escape, an outside click, or a swipe to the right; focus returns to the selected invocation. The portal stays within the observer's theme scope, and long details scroll below the header.
|
|
42
46
|
|
|
43
47
|
Durations include queue wait, actor processing, and persistence. Gaps are calculated only from the calls loaded in the current view; filtered or unretained calls are not included. The waterfall uses request traces, so internal helper calls within one invocation are not separate spans. Embed `RequestTimeline` directly with `records` and an `onSelect(record, trigger)` callback when providing your own request controls.
|
|
44
48
|
|
|
49
|
+
## Actor instances and residency
|
|
50
|
+
|
|
51
|
+
Actor pages list every known instance, ordered by its latest request activity, including dormant instances. The Last active column shows a relative time with the exact timestamp on hover; unavailable timestamps sort last. Activity timestamps include request admission and completion, and do not advance on lifecycle heartbeats.
|
|
52
|
+
|
|
53
|
+
Residency and WebSocket timelines share the same axis, row labels, bars, and time scale. The residency timeline shows one lane per instance in the same order as the list. Green segments mean in memory, purple means dormant, and hatching means unknown. Search and state filters apply to both views. Hover or focus a segment for its timestamps and duration; select a segment or instance to inspect it. The shared time range controls the timeline, while the inventory continues to list all known instances.
|
|
54
|
+
|
|
55
|
+
Residency uses lifecycle reports, including immediate notifications when the executor loads or evicts an instance. Missing reports become unknown after 35 seconds; stopped hosts remain dormant until a later activation. Time before retained evidence is blank. ClickHouse history follows analytics retention; the local and Postgres analytics runtimes retain up to 100,000 lifecycle reports for 24 hours in memory, and their inventory lasts for the runtime process (up to 10,000 instances). Timeline queries return the latest 10,000 reports and show a notice when truncated. Older deployments without activity timestamps display Unknown until the next request.
|
|
56
|
+
|
|
57
|
+
Custom observer clients can implement `listResidency` to enable the timeline. `HttpObserverClient` and the TypeScript and Python observer proxies use the authenticated project endpoint `/v1/projects/{project_id}/observe/residency?actorName=…`. `ResidencyTimeline` and its props and data types are also exported for embedding.
|
|
58
|
+
|
|
45
59
|
## Persisted actor state
|
|
46
60
|
|
|
47
61
|
Select an actor instance in `ActorObserver` to inspect persisted fields, JSON types, nested values, and version diffs. Request and connection links filter the existing request history. The standard `HttpObserverClient` and `durable-actors observe` include this capability; custom clients implement `getState` and `listStateHistory` to enable it.
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import type { ComponentProps, ReactNode } from "react";
|
|
2
|
+
interface InstanceTimelineProps {
|
|
3
|
+
start: number;
|
|
4
|
+
end: number;
|
|
5
|
+
endLabel?: string;
|
|
6
|
+
label: string;
|
|
7
|
+
children: (scale: TimelineScale) => ReactNode;
|
|
8
|
+
footer?: ReactNode;
|
|
9
|
+
overlay?: ReactNode;
|
|
10
|
+
onMouseLeave?: () => void;
|
|
11
|
+
}
|
|
12
|
+
export declare function InstanceTimeline({ start, end, endLabel, label, children, footer, overlay, onMouseLeave }: InstanceTimelineProps): import("react").JSX.Element;
|
|
13
|
+
export declare function InstanceTimelineRow({ actorName, actorId, tracks, children }: {
|
|
14
|
+
actorName?: string;
|
|
15
|
+
actorId: string;
|
|
16
|
+
tracks?: number;
|
|
17
|
+
children: ReactNode;
|
|
18
|
+
}): import("react").JSX.Element;
|
|
19
|
+
export declare function InstanceTimelineBar({ scale, from, to, track, className, style, ...props }: ComponentProps<"button"> & {
|
|
20
|
+
scale: TimelineScale;
|
|
21
|
+
from: number;
|
|
22
|
+
to: number;
|
|
23
|
+
track?: number;
|
|
24
|
+
}): import("react").JSX.Element;
|
|
25
|
+
export declare function useTimelineHover<T>(): {
|
|
26
|
+
hover: {
|
|
27
|
+
item: T;
|
|
28
|
+
left: number;
|
|
29
|
+
top: number;
|
|
30
|
+
below: boolean;
|
|
31
|
+
} | undefined;
|
|
32
|
+
show: (item: T, target: HTMLElement) => void;
|
|
33
|
+
hide: () => void;
|
|
34
|
+
};
|
|
35
|
+
type TimelineScale = ReturnType<typeof timelineScale>;
|
|
36
|
+
declare function timelineScale(start: number, end: number): {
|
|
37
|
+
span: number;
|
|
38
|
+
position: (time: number) => string;
|
|
39
|
+
interval: (from: number, to: number) => {
|
|
40
|
+
left: string;
|
|
41
|
+
width: string;
|
|
42
|
+
};
|
|
43
|
+
};
|
|
44
|
+
export declare function timelineTicks(start: number, end: number): number[];
|
|
45
|
+
export {};
|
|
@@ -1,15 +1,16 @@
|
|
|
1
|
-
import type { ObserverClient, RequestTrace } from "./client.js";
|
|
1
|
+
import type { ActorInventory, ObserverClient, RequestTrace } from "./client.js";
|
|
2
2
|
import type { TimeRange } from "./time-range.js";
|
|
3
3
|
interface RequestObserverProps {
|
|
4
4
|
focus?: {
|
|
5
5
|
requestId?: string;
|
|
6
6
|
connectionId?: string;
|
|
7
7
|
};
|
|
8
|
-
client: Pick<ObserverClient, "watchRequests" | "listRequests"
|
|
8
|
+
client: Pick<ObserverClient, "watchRequests" | "listRequests"> & Partial<Pick<ObserverClient, "listActors" | "watchActors">>;
|
|
9
9
|
actor?: Pick<RequestTrace, "actorName" | "actorId">;
|
|
10
|
+
inventory?: ActorInventory;
|
|
10
11
|
timeRange?: TimeRange;
|
|
11
12
|
onTimeRangeChange?: (range: TimeRange) => void;
|
|
12
13
|
}
|
|
13
|
-
declare function RequestObserver({ client, actor, timeRange, onTimeRangeChange, focus }: RequestObserverProps): import("react").JSX.Element;
|
|
14
|
+
declare function RequestObserver({ client, actor, inventory: providedInventory, timeRange, onTimeRangeChange, focus }: RequestObserverProps): import("react").JSX.Element;
|
|
14
15
|
export { RequestObserver };
|
|
15
16
|
export type { RequestObserverProps };
|
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
import type { RequestTrace } from "./client.js";
|
|
2
|
+
import type { RequestTimelineLane } from "./request-timeline.js";
|
|
2
3
|
export interface RequestTimelineProps {
|
|
3
4
|
records: RequestTrace[];
|
|
5
|
+
lanes?: RequestTimelineLane[];
|
|
4
6
|
selected?: RequestTrace;
|
|
5
7
|
onSelect: (record: RequestTrace, trigger: HTMLButtonElement) => void;
|
|
6
8
|
}
|
|
7
|
-
export declare function RequestTimeline({ records, selected, onSelect }: RequestTimelineProps): import("react").JSX.Element;
|
|
9
|
+
export declare function RequestTimeline({ records, lanes, selected, onSelect }: RequestTimelineProps): import("react").JSX.Element;
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import type { ActorInstance } from "./client.js";
|
|
2
|
+
import type { ResidencyPeriod } from "./residency.js";
|
|
3
|
+
export interface ResidencyTimelineProps {
|
|
4
|
+
instances: ActorInstance[];
|
|
5
|
+
periods: ResidencyPeriod[];
|
|
6
|
+
start: number;
|
|
7
|
+
end: number;
|
|
8
|
+
endLabel?: string;
|
|
9
|
+
onSelect: (actorId: string) => void;
|
|
10
|
+
}
|
|
11
|
+
export declare function ResidencyTimeline({ instances, periods, start, end, endLabel, onSelect }: ResidencyTimelineProps): import("react").JSX.Element;
|
package/dist/SocketTimeline.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { SocketSession } from "./socket-sessions.js";
|
|
2
|
+
export { timelineTicks } from "./InstanceTimeline.js";
|
|
2
3
|
export interface SocketTimelineProps {
|
|
3
4
|
sessions: SocketSession[];
|
|
4
5
|
start: number;
|
|
@@ -22,8 +23,6 @@ interface Placed {
|
|
|
22
23
|
}
|
|
23
24
|
export declare function SocketTimeline({ sessions, start, end, endLabel, selected, onSelect }: SocketTimelineProps): import("react").JSX.Element;
|
|
24
25
|
export declare function packLanes(sessions: SocketSession[], start: number, end: number): Lane[];
|
|
25
|
-
export declare function
|
|
26
|
-
export declare function statusLabel(status: SocketSession["status"]): "Open" | "Closed" | "Unknown" | "Lost";
|
|
26
|
+
export declare function statusLabel(status: SocketSession["status"]): "Unknown" | "Open" | "Closed" | "Lost";
|
|
27
27
|
export declare function durationLabel(session: SocketSession, now: number): string;
|
|
28
28
|
export declare function shortId(id: string): string;
|
|
29
|
-
export {};
|
package/dist/client.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { type OverviewMetrics } from "./overview-metrics.js";
|
|
2
2
|
import { type QueueWaitRow } from "./queue-wait.js";
|
|
3
|
+
import { type ResidencyHistory, type ResidencyQuery } from "./residency.js";
|
|
3
4
|
import { type SocketSessionRow } from "./socket-sessions.js";
|
|
4
5
|
import { type StateHistoryPage, type StateQuery, type StateResponse } from "./state-data.js";
|
|
5
6
|
import type { ResolvedRange } from "./time-range.js";
|
|
@@ -7,6 +8,7 @@ type ActorResidency = "live" | "dormant" | "unknown";
|
|
|
7
8
|
interface ActorInstance {
|
|
8
9
|
actorId: string;
|
|
9
10
|
status: ActorResidency;
|
|
11
|
+
lastActiveAtMs?: number | null;
|
|
10
12
|
connections: ActorConnection[];
|
|
11
13
|
waiting?: {
|
|
12
14
|
id: string;
|
|
@@ -21,6 +23,7 @@ interface ActorInventory {
|
|
|
21
23
|
connectionsComplete: boolean;
|
|
22
24
|
actors: {
|
|
23
25
|
actorName: string;
|
|
26
|
+
methods?: string[];
|
|
24
27
|
live: number;
|
|
25
28
|
dormant: number;
|
|
26
29
|
unknown: number;
|
|
@@ -28,6 +31,7 @@ interface ActorInventory {
|
|
|
28
31
|
}[];
|
|
29
32
|
}
|
|
30
33
|
interface ObserverClient {
|
|
34
|
+
listResidency?(query: ResidencyQuery, signal?: AbortSignal): Promise<ResidencyHistory>;
|
|
31
35
|
getState?(query: StateQuery, signal?: AbortSignal): Promise<StateResponse>;
|
|
32
36
|
listStateHistory?(query: Omit<StateQuery, "version"> & {
|
|
33
37
|
before?: number;
|
|
@@ -48,6 +52,7 @@ declare class HttpObserverClient implements ObserverClient {
|
|
|
48
52
|
private readonly baseUrl;
|
|
49
53
|
private readonly request;
|
|
50
54
|
constructor(baseUrl?: string, request?: typeof fetch);
|
|
55
|
+
listResidency(query: ResidencyQuery, signal?: AbortSignal): Promise<ResidencyHistory>;
|
|
51
56
|
getState(query: StateQuery, signal?: AbortSignal): Promise<StateResponse>;
|
|
52
57
|
listStateHistory(query: Omit<StateQuery, "version"> & {
|
|
53
58
|
before?: number;
|
package/dist/index.d.ts
CHANGED
|
@@ -10,6 +10,10 @@ export { RequestObserver } from "./RequestObserver.js";
|
|
|
10
10
|
export type { RequestObserverProps } from "./RequestObserver.js";
|
|
11
11
|
export { RequestTimeline } from "./RequestTimeline.js";
|
|
12
12
|
export type { RequestTimelineProps } from "./RequestTimeline.js";
|
|
13
|
+
export type { RequestTimelineLane } from "./request-timeline.js";
|
|
14
|
+
export { ResidencyTimeline } from "./ResidencyTimeline.js";
|
|
15
|
+
export type { ResidencyTimelineProps } from "./ResidencyTimeline.js";
|
|
16
|
+
export type { ResidencyHistory, ResidencyPeriod, ResidencyQuery } from "./residency.js";
|
|
13
17
|
export { SocketTimeline } from "./SocketTimeline.js";
|
|
14
18
|
export type { SocketTimelineProps } from "./SocketTimeline.js";
|
|
15
19
|
export { TimeRangePicker } from "./TimeRangePicker.js";
|