@contractspec/bundle.library 3.9.3 → 3.9.5
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/.turbo/turbo-build.log +9 -6
- package/CHANGELOG.md +72 -0
- package/dist/components/docs/advanced/AdvancedSpecExperimentsPage.js +4 -4
- package/dist/components/docs/advanced/index.js +10 -10
- package/dist/components/docs/index.js +168 -168
- package/dist/components/docs/libraries/LibrariesCrossPlatformUIPage.content.d.ts +3 -3
- package/dist/components/docs/libraries/LibrariesCrossPlatformUIPage.content.js +2 -2
- package/dist/components/docs/libraries/LibrariesCrossPlatformUIPage.js +2 -2
- package/dist/components/docs/libraries/index.js +2 -2
- package/dist/index.js +179 -179
- package/dist/node/components/docs/advanced/AdvancedSpecExperimentsPage.js +4 -4
- package/dist/node/components/docs/advanced/index.js +10 -10
- package/dist/node/components/docs/index.js +168 -168
- package/dist/node/components/docs/libraries/LibrariesCrossPlatformUIPage.content.js +2 -2
- package/dist/node/components/docs/libraries/LibrariesCrossPlatformUIPage.js +2 -2
- package/dist/node/components/docs/libraries/index.js +2 -2
- package/dist/node/index.js +179 -179
- package/package.json +27 -27
- package/src/components/docs/advanced/AdvancedSpecExperimentsPage.tsx +22 -14
- package/src/components/docs/generated/docs-index.manifest.json +1 -1
- package/src/components/docs/libraries/LibrariesCrossPlatformUIPage.content.ts +3 -3
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
var
|
|
1
|
+
var D=Object.defineProperty;var E=(f)=>f;function F(f,q){this[f]=E.bind(null,q)}var J=(f,q)=>{for(var w in q)D(f,w,{get:q[w],enumerable:!0,configurable:!0,set:F.bind(q,w)})};var K=(f,q)=>()=>(f&&(q=f(f=0)),q);import{Code as z,H1 as G,H2 as A,H3 as I,P as B}from"@contractspec/lib.design-system/components/typography";import{jsx as k,jsxs as v}from"react/jsx-runtime";function N(){return v("div",{className:"space-y-8",children:[v("div",{className:"space-y-4",children:[k(G,{className:"font-bold text-4xl",children:"Spec Experiments"}),k(B,{className:"text-lg text-muted-foreground",children:"Run controlled experiments on ContractSpec operations, gradually shift traffic, and roll back automatically when guardrails trip."})]}),v("div",{className:"space-y-3",children:[k(A,{className:"font-bold text-2xl",children:"Define control + variants"}),k(z,{className:"rounded-lg border bg-muted p-4 text-sm",children:`import { SpecExperimentRegistry } from '@contractspec/lib.growth/spec-experiments';
|
|
2
2
|
|
|
3
3
|
const registry = new SpecExperimentRegistry().register({
|
|
4
4
|
target: { name: 'billing.createInvoice', version: 4 },
|
|
@@ -18,12 +18,12 @@ const registry = new SpecExperimentRegistry().register({
|
|
|
18
18
|
],
|
|
19
19
|
rolloutStages: [0.01, 0.1, 0.5, 1],
|
|
20
20
|
guardrails: { errorRateThreshold: 0.02, latencyP99ThresholdMs: 500 },
|
|
21
|
-
});`})]}),
|
|
21
|
+
});`})]}),v("div",{className:"space-y-3",children:[k(A,{className:"font-bold text-2xl",children:"Attach to runtime"}),k(z,{className:"rounded-lg border bg-muted p-4 text-sm",children:`import { createSpecVariantResolver } from '@contractspec/lib.growth/spec-experiments';
|
|
22
22
|
|
|
23
23
|
adapterContext.specVariantResolver = createSpecVariantResolver({
|
|
24
24
|
adapter,
|
|
25
25
|
resolveUserId: (ctx) => ctx.userId ?? ctx.organizationId ?? 'anon',
|
|
26
|
-
});`})]}),
|
|
26
|
+
});`})]}),v("div",{className:"space-y-3",children:[k(A,{className:"font-bold text-2xl",children:"Track outcomes + auto-rollback"}),k(z,{className:"rounded-lg border bg-muted p-4 text-sm",children:`import {
|
|
27
27
|
SpecExperimentAnalyzer,
|
|
28
28
|
SpecExperimentController,
|
|
29
29
|
} from '@contractspec/lib.growth/spec-experiments';
|
|
@@ -33,4 +33,4 @@ const controller = new SpecExperimentController({
|
|
|
33
33
|
registry,
|
|
34
34
|
analyzer,
|
|
35
35
|
onRollback: (target, evaluation) => notifyOps(target, evaluation.reasons),
|
|
36
|
-
});`})]}),
|
|
36
|
+
});`})]}),k("div",{className:"grid gap-4 md:grid-cols-2",children:[{title:"Deterministic bucketing",description:"ExperimentRunner reuses the same hashing logic as growth experiments—every user sticks to a variant."},{title:"Multi-stage rollouts",description:"Use `rolloutStages` to shift 1% → 10% → 50% → 100%. Guardrails trigger rollbacks automatically."}].map((f)=>v("div",{className:"card-subtle space-y-2 p-4",children:[k(I,{className:"font-semibold text-lg",children:f.title}),k(B,{className:"text-muted-foreground text-sm",children:f.description})]},f.title))})]})}export{N as AdvancedSpecExperimentsPage};
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
var
|
|
1
|
+
var N=Object.defineProperty;var w=(l)=>l;function k(l,p){this[l]=w.bind(null,p)}var R=(l,p)=>{for(var f in p)N(l,f,{get:p[f],enumerable:!0,configurable:!0,set:k.bind(p,f)})};var L=(l,p)=>()=>(l&&(p=l(l=0)),p);import g from"@contractspec/lib.ui-link";import{ChevronRight as S}from"lucide-react";import{jsx as t,jsxs as a}from"react/jsx-runtime";function U(){return a("div",{className:"space-y-8",children:[a("div",{className:"space-y-4",children:[t("h1",{className:"font-bold text-4xl",children:"MCP Adapters"}),a("p",{className:"text-muted-foreground",children:["The ",t("strong",{children:"Model Context Protocol (MCP)"})," is an open standard for connecting AI models to external tools and data sources. ContractSpec provides MCP adapters that allow you to expose your capabilities as MCP tools and consume external MCP servers as capabilities."]})]}),a("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"Why MCP integration matters"}),t("p",{className:"text-muted-foreground",children:"AI agents need access to real-world tools and data to be useful. MCP provides a standardized way to expose these capabilities. By integrating ContractSpec with MCP, you can:"}),a("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[t("li",{children:"Let AI agents invoke your ContractSpec capabilities safely and securely"}),t("li",{children:"Use external MCP servers (databases, APIs, search engines) as capability providers in your workflows"}),t("li",{children:"Build AI-powered features without writing custom integration code"}),t("li",{children:"Enforce policies on AI agent actions just like any other user"})]})]}),a("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"Exposing capabilities as MCP tools"}),a("p",{className:"text-muted-foreground",children:["Any"," ",t(g,{href:"/docs/specs/capabilities",className:"text-violet-400 hover:text-violet-300",children:"CapabilitySpec"})," ","can be automatically exposed as an MCP tool. ContractSpec generates:"]}),a("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[t("li",{children:"A tool schema describing the capability's inputs, outputs, and purpose"}),t("li",{children:"An MCP server endpoint that AI agents can connect to"}),t("li",{children:"Policy enforcement ensuring agents can only invoke capabilities they're authorized to use"}),t("li",{children:"Audit logging of all agent actions for compliance and debugging"})]})]}),a("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"Example: Exposing a capability"}),t("p",{className:"text-muted-foreground",children:"Here's how to expose ContractSpec operations as MCP tools:"}),t("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:t("pre",{children:`import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
2
2
|
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
|
3
3
|
import { createMcpServer } from '@contractspec/lib.contracts-runtime-server-mcp/provider-mcp';
|
|
4
4
|
import { registry, resources, prompts } from './lib/registry';
|
|
@@ -15,7 +15,7 @@ createMcpServer(server, registry, resources, prompts, {
|
|
|
15
15
|
});
|
|
16
16
|
|
|
17
17
|
const transport = new StdioServerTransport();
|
|
18
|
-
await server.connect(transport);`})}),t("p",{className:"text-muted-foreground",children:"AI agents can now discover and invoke your operations through the MCP protocol. ContractSpec handles authentication, authorization, and execution automatically via the `OperationSpecRegistry`."})]}),
|
|
18
|
+
await server.connect(transport);`})}),t("p",{className:"text-muted-foreground",children:"AI agents can now discover and invoke your operations through the MCP protocol. ContractSpec handles authentication, authorization, and execution automatically via the `OperationSpecRegistry`."})]}),a("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"Consuming external MCP servers"}),t("p",{className:"text-muted-foreground",children:"You can integrate external MCP servers into your workflows. Define an integration spec and use it in your operations:"}),t("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:t("pre",{children:`import { defineIntegration } from '@contractspec/lib.contracts-integrations';
|
|
19
19
|
import { SchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
|
|
20
20
|
|
|
21
21
|
const SearchProductsIntegration = defineIntegration({
|
|
@@ -44,7 +44,7 @@ const SearchProductsIntegration = defineIntegration({
|
|
|
44
44
|
},
|
|
45
45
|
}),
|
|
46
46
|
},
|
|
47
|
-
});`})})]}),
|
|
47
|
+
});`})})]}),a("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"Policy enforcement for AI agents"}),a("p",{className:"text-muted-foreground",children:["AI agents are treated like any other actor in ContractSpec. They must authenticate, and all their actions are subject to"," ",t(g,{href:"/docs/specs/policy",className:"text-violet-400 hover:text-violet-300",children:"PolicySpecs"}),". You can define specific policies in TypeScript:"]}),t("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:t("pre",{children:`import { definePolicy } from '@contractspec/lib.contracts-spec';
|
|
48
48
|
|
|
49
49
|
export const AIAgentRestrictions = definePolicy({
|
|
50
50
|
meta: {
|
|
@@ -67,7 +67,7 @@ export const AIAgentRestrictions = definePolicy({
|
|
|
67
67
|
!ctx.approvalGranted,
|
|
68
68
|
},
|
|
69
69
|
],
|
|
70
|
-
});`})})]}),
|
|
70
|
+
});`})})]}),a("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"Human-in-the-loop workflows"}),t("p",{className:"text-muted-foreground",children:"For sensitive operations, you can require human approval before an AI agent can proceed. ContractSpec provides built-in approval workflows:"}),a("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[t("li",{children:"Agent requests permission to invoke a capability"}),t("li",{children:"Request is sent to designated approvers (via email, Slack, etc.)"}),t("li",{children:"Approver reviews the request and approves or denies it"}),t("li",{children:"Agent receives the decision and can proceed if approved"})]}),a("p",{className:"text-muted-foreground",children:["All approval decisions are logged in the"," ",t(g,{href:"/docs/safety/auditing",className:"text-violet-400 hover:text-violet-300",children:"audit log"}),"."]})]}),a("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"Best practices"}),a("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[t("li",{children:"Start with read-only capabilities for AI agents—only grant write access when necessary."}),t("li",{children:"Use human-in-the-loop approval for any capability that modifies critical data or triggers financial transactions."}),t("li",{children:"Set rate limits to prevent runaway agents from overwhelming your system."}),t("li",{children:"Provide clear, detailed descriptions for each capability so agents know when to use them."}),t("li",{children:"Monitor agent actions closely in production and adjust policies as needed."}),t("li",{children:"Test agent integrations thoroughly with realistic scenarios before deploying."})]})]}),a("div",{className:"flex items-center gap-4 pt-4",children:[t(g,{href:"/docs/advanced/renderers",className:"btn-ghost",children:"Previous: Custom Renderers"}),a(g,{href:"/docs/advanced/telemetry",className:"btn-primary",children:["Next: Telemetry ",t(S,{size:16})]})]})]})}import C from"@contractspec/lib.ui-link";import{jsx as r,jsxs as d}from"react/jsx-runtime";function Y(){return d("div",{className:"space-y-8",children:[d("div",{className:"space-y-4",children:[r("h1",{className:"font-bold text-4xl",children:"Overlay Editor"}),r("p",{className:"text-lg text-muted-foreground",children:"A Next.js app (`@contractspec/app.overlay-editor`) that lets tenant admins tweak field visibility, labels, and ordering, then sign OverlaySpecs."})]}),d("div",{className:"space-y-4",children:[r("h2",{className:"font-bold text-2xl",children:"Features"}),d("ul",{className:"list-disc space-y-2 pl-6",children:[r("li",{children:"Toggle visibility and rename labels without touching code."}),r("li",{children:"Move fields up/down to define the overlay order."}),r("li",{children:"Preview JSON output powered by `@contractspec/lib.overlay-engine`."}),r("li",{children:"Server action for PEM signing (Ed25519/RSA-PSS)."})]}),d("p",{children:["Project path: ",r("code",{children:"packages/apps/overlay-editor"})]})]}),d("div",{className:"space-y-4",children:[r("h2",{className:"font-bold text-2xl",children:"Provisioning flow"}),d("ol",{className:"list-decimal space-y-2 pl-6",children:[d("li",{children:["Clone the repo and run ",r("code",{children:"bun dev"})," inside the app."]}),r("li",{children:"Use the UI to craft the overlay for a tenant."}),r("li",{children:"Paste the tenant's PEM private key (stored in Vault/KMS)."}),r("li",{children:"Click “Sign overlay” to get the final JSON payload."}),r("li",{children:"Persist in the `Overlay` table and register with `OverlayRegistry`."})]}),d("p",{children:["See also:"," ",r(C,{href:"/docs/ops/tenant-customization",className:"text-violet-400 underline",children:"Tenant customization runbook"}),"."]})]})]})}import P from"@contractspec/lib.ui-link";import{ChevronRight as A}from"lucide-react";import{jsx as i,jsxs as s}from"react/jsx-runtime";function V(){return s("div",{className:"space-y-8",children:[s("div",{className:"space-y-2",children:[i("h1",{className:"font-bold text-4xl",children:"Custom Renderers"}),i("p",{className:"text-lg text-muted-foreground",children:"ContractSpec ships with React and React Native renderers. You can build custom renderers for any framework."})]}),s("div",{className:"space-y-6",children:[s("div",{className:"space-y-3",children:[i("h2",{className:"font-bold text-2xl",children:"Overview"}),s("p",{className:"text-muted-foreground",children:["The presentation runtime libraries (",i("code",{children:"@contractspec/lib.presentation-runtime-react"})," and",i("code",{children:"@contractspec/lib.presentation-runtime-react-native"}),") provide hooks and components to render ContractSpec-defined UI like workflows and data views. You can extend these or create custom implementations for other frameworks."]})]}),s("div",{className:"space-y-3",children:[i("h2",{className:"font-bold text-2xl",children:"Using the React Renderer"}),i("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:i("pre",{children:`import { useWorkflow, WorkflowStepRenderer } from '@contractspec/lib.presentation-runtime-react';
|
|
71
71
|
import { MyWorkflowSpec } from './specs';
|
|
72
72
|
|
|
73
73
|
export function WorkflowPage() {
|
|
@@ -82,7 +82,7 @@ export function WorkflowPage() {
|
|
|
82
82
|
</button>
|
|
83
83
|
</div>
|
|
84
84
|
);
|
|
85
|
-
}`})})]}),
|
|
85
|
+
}`})})]}),s("div",{className:"space-y-3",children:[i("h2",{className:"font-bold text-2xl",children:"Custom Platform Support"}),i("p",{className:"text-muted-foreground",children:"To support a new platform (e.g., Vue, Svelte), you would:"}),s("ol",{className:"list-inside list-decimal space-y-2 text-muted-foreground",children:[s("li",{children:["Implement the core workflow state machine (from"," ",i("code",{children:"@contractspec/lib.presentation-runtime-core"}),")"]}),i("li",{children:"Create framework-specific hooks/components for step rendering"}),i("li",{children:"Handle validation and submission via the ContractSpec I/O schemas"})]})]}),i("div",{className:"flex items-center gap-4 pt-4",children:s(P,{href:"/docs",className:"btn-primary",children:["Back to docs ",i(A,{size:16})]})})]})]})}import{Code as v,H1 as M,H2 as h,H3 as T,P as y}from"@contractspec/lib.design-system/components/typography";import{jsx as c,jsxs as u}from"react/jsx-runtime";function H(){return u("div",{className:"space-y-8",children:[u("div",{className:"space-y-4",children:[c(M,{className:"font-bold text-4xl",children:"Spec Experiments"}),c(y,{className:"text-lg text-muted-foreground",children:"Run controlled experiments on ContractSpec operations, gradually shift traffic, and roll back automatically when guardrails trip."})]}),u("div",{className:"space-y-3",children:[c(h,{className:"font-bold text-2xl",children:"Define control + variants"}),c(v,{className:"rounded-lg border bg-muted p-4 text-sm",children:`import { SpecExperimentRegistry } from '@contractspec/lib.growth/spec-experiments';
|
|
86
86
|
|
|
87
87
|
const registry = new SpecExperimentRegistry().register({
|
|
88
88
|
target: { name: 'billing.createInvoice', version: 4 },
|
|
@@ -102,12 +102,12 @@ const registry = new SpecExperimentRegistry().register({
|
|
|
102
102
|
],
|
|
103
103
|
rolloutStages: [0.01, 0.1, 0.5, 1],
|
|
104
104
|
guardrails: { errorRateThreshold: 0.02, latencyP99ThresholdMs: 500 },
|
|
105
|
-
});`})]}),u("div",{className:"space-y-3",children:[
|
|
105
|
+
});`})]}),u("div",{className:"space-y-3",children:[c(h,{className:"font-bold text-2xl",children:"Attach to runtime"}),c(v,{className:"rounded-lg border bg-muted p-4 text-sm",children:`import { createSpecVariantResolver } from '@contractspec/lib.growth/spec-experiments';
|
|
106
106
|
|
|
107
107
|
adapterContext.specVariantResolver = createSpecVariantResolver({
|
|
108
108
|
adapter,
|
|
109
109
|
resolveUserId: (ctx) => ctx.userId ?? ctx.organizationId ?? 'anon',
|
|
110
|
-
});`})]}),u("div",{className:"space-y-3",children:[
|
|
110
|
+
});`})]}),u("div",{className:"space-y-3",children:[c(h,{className:"font-bold text-2xl",children:"Track outcomes + auto-rollback"}),c(v,{className:"rounded-lg border bg-muted p-4 text-sm",children:`import {
|
|
111
111
|
SpecExperimentAnalyzer,
|
|
112
112
|
SpecExperimentController,
|
|
113
113
|
} from '@contractspec/lib.growth/spec-experiments';
|
|
@@ -117,7 +117,7 @@ const controller = new SpecExperimentController({
|
|
|
117
117
|
registry,
|
|
118
118
|
analyzer,
|
|
119
119
|
onRollback: (target, evaluation) => notifyOps(target, evaluation.reasons),
|
|
120
|
-
});`})]}),
|
|
120
|
+
});`})]}),c("div",{className:"grid gap-4 md:grid-cols-2",children:[{title:"Deterministic bucketing",description:"ExperimentRunner reuses the same hashing logic as growth experiments—every user sticks to a variant."},{title:"Multi-stage rollouts",description:"Use `rolloutStages` to shift 1% → 10% → 50% → 100%. Guardrails trigger rollbacks automatically."}].map((l)=>u("div",{className:"card-subtle space-y-2 p-4",children:[c(T,{className:"font-semibold text-lg",children:l.title}),c(y,{className:"text-muted-foreground text-sm",children:l.description})]},l.title))})]})}import b from"@contractspec/lib.ui-link";import{ChevronRight as I}from"lucide-react";import{jsx as e,jsxs as o}from"react/jsx-runtime";function j(){return o("div",{className:"space-y-8",children:[o("div",{className:"space-y-4",children:[e("h1",{className:"font-bold text-4xl",children:"Telemetry"}),o("p",{className:"text-muted-foreground",children:["A ",e("strong",{children:"TelemetrySpec"})," defines what metrics, logs, and traces to collect for observability. ContractSpec automatically instruments your application based on these specs, ensuring you have the visibility you need to monitor, debug, and optimize your system."]})]}),o("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Why telemetry matters"}),e("p",{className:"text-muted-foreground",children:"You can't fix what you can't see. Telemetry provides visibility into how your application is performing, where errors are occurring, and how users are interacting with your system. Without proper instrumentation, you're flying blind in production."}),e("p",{className:"text-muted-foreground",children:"ContractSpec takes a spec-first approach to telemetry: you declare what you want to observe, and runtime adapters instrument operations automatically. This ensures consistent, comprehensive coverage without manual effort."})]}),o("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Three pillars of observability"}),o("div",{className:"space-y-3",children:[o("div",{children:[e("h3",{className:"font-semibold text-lg",children:"Metrics"}),e("p",{className:"text-muted-foreground",children:"Numerical measurements collected over time. Examples: request count, error rate, latency percentiles, active users, queue depth. Metrics are cheap to collect and store, making them ideal for high-level monitoring and alerting."})]}),o("div",{children:[e("h3",{className:"font-semibold text-lg",children:"Logs"}),e("p",{className:"text-muted-foreground",children:'Timestamped text records of events. Examples: "User 123 logged in", "Payment failed for order 456", "Database connection pool exhausted". Logs provide detailed context for debugging specific issues.'})]}),o("div",{children:[e("h3",{className:"font-semibold text-lg",children:"Traces"}),e("p",{className:"text-muted-foreground",children:"Records of requests as they flow through your system. A trace shows the complete path of a request—which services it touched, how long each step took, and where errors occurred. Traces are essential for debugging distributed systems."})]})]})]}),o("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Example TelemetrySpec"}),e("p",{className:"text-muted-foreground",children:"Here's how telemetry is configured in TypeScript:"}),e("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:e("pre",{children:`import { defineTelemetry } from '@contractspec/lib.contracts-spec/telemetry';
|
|
121
121
|
|
|
122
122
|
export const OrderProcessingTelemetry = defineTelemetry({
|
|
123
123
|
meta: {
|
|
@@ -162,7 +162,7 @@ export const OrderProcessingTelemetry = defineTelemetry({
|
|
|
162
162
|
notify: ['pagerduty', 'slack'],
|
|
163
163
|
},
|
|
164
164
|
],
|
|
165
|
-
});`})})]}),o("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Automatic instrumentation"}),e("p",{className:"text-muted-foreground",children:"ContractSpec automatically instruments:"}),o("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[o("li",{children:[e("strong",{children:"All operations"})," – Request count, latency, error rate per Command/Query"]}),o("li",{children:[e("strong",{children:"All workflows"})," – Step execution time, retry counts, compensation events"]}),o("li",{children:[e("strong",{children:"All data views"})," – Query execution time, result set size"]}),o("li",{children:[e("strong",{children:"All policy decisions"})," – Decision time, permit/deny ratio"]}),o("li",{children:[e("strong",{children:"System resources"})," – CPU, memory, disk, network usage"]})]}),e("p",{className:"text-muted-foreground",children:"You don't need to add instrumentation code manually—the runtime handles it based on your specs."})]}),o("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Integration with observability platforms"}),e("p",{className:"text-muted-foreground",children:"ContractSpec supports multiple observability backends:"}),o("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[o("li",{children:[e("strong",{children:"Prometheus"})," – For metrics collection and alerting"]}),o("li",{children:[e("strong",{children:"Grafana"})," – For dashboards and visualization"]}),o("li",{children:[e("strong",{children:"Jaeger / Tempo"})," – For distributed tracing"]}),o("li",{children:[e("strong",{children:"Loki"})," – For log aggregation"]}),o("li",{children:[e("strong",{children:"Datadog"})," – All-in-one observability platform"]}),o("li",{children:[e("strong",{children:"New Relic"})," – Application performance monitoring"]}),o("li",{children:[e("strong",{children:"Honeycomb"})," – Observability for complex systems"]})]}),e("p",{className:"text-muted-foreground",children:"You can configure multiple backends and send telemetry to all of them simultaneously."})]}),o("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Sampling and performance"}),e("p",{className:"text-muted-foreground",children:"Collecting telemetry has a cost—CPU, memory, network bandwidth, and storage. ContractSpec provides several mechanisms to control overhead:"}),o("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[o("li",{children:[e("strong",{children:"Sampling"})," – Trace only a percentage of requests (e.g., 10%)"]}),o("li",{children:[e("strong",{children:"Adaptive sampling"})," – Automatically reduce sampling rate under high load"]}),o("li",{children:[e("strong",{children:"Tail-based sampling"})," – Keep traces for failed requests, sample successful ones"]}),o("li",{children:[e("strong",{children:"Field redaction"})," – Remove sensitive data from traces and logs"]}),o("li",{children:[e("strong",{children:"Aggregation"})," – Pre-aggregate metrics before sending to reduce network traffic"]})]})]}),o("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Best practices"}),o("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[e("li",{children:"Start with high-level metrics (request rate, error rate, latency) and add more detailed instrumentation as needed."}),e("li",{children:"Use structured logging—log events with structured fields, not free-form text."}),e("li",{children:"Set up alerts for critical metrics so you're notified when things go wrong."}),e("li",{children:"Use traces to debug complex issues—they show the complete picture of a request."}),e("li",{children:"Redact sensitive data from logs and traces to comply with privacy regulations."}),e("li",{children:"Review dashboards regularly to understand normal behavior—this makes anomalies easier to spot."}),e("li",{children:"Use sampling to control costs, but always trace errors and slow requests."})]})]}),o("div",{className:"flex items-center gap-4 pt-4",children:[e(
|
|
165
|
+
});`})})]}),o("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Automatic instrumentation"}),e("p",{className:"text-muted-foreground",children:"ContractSpec automatically instruments:"}),o("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[o("li",{children:[e("strong",{children:"All operations"})," – Request count, latency, error rate per Command/Query"]}),o("li",{children:[e("strong",{children:"All workflows"})," – Step execution time, retry counts, compensation events"]}),o("li",{children:[e("strong",{children:"All data views"})," – Query execution time, result set size"]}),o("li",{children:[e("strong",{children:"All policy decisions"})," – Decision time, permit/deny ratio"]}),o("li",{children:[e("strong",{children:"System resources"})," – CPU, memory, disk, network usage"]})]}),e("p",{className:"text-muted-foreground",children:"You don't need to add instrumentation code manually—the runtime handles it based on your specs."})]}),o("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Integration with observability platforms"}),e("p",{className:"text-muted-foreground",children:"ContractSpec supports multiple observability backends:"}),o("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[o("li",{children:[e("strong",{children:"Prometheus"})," – For metrics collection and alerting"]}),o("li",{children:[e("strong",{children:"Grafana"})," – For dashboards and visualization"]}),o("li",{children:[e("strong",{children:"Jaeger / Tempo"})," – For distributed tracing"]}),o("li",{children:[e("strong",{children:"Loki"})," – For log aggregation"]}),o("li",{children:[e("strong",{children:"Datadog"})," – All-in-one observability platform"]}),o("li",{children:[e("strong",{children:"New Relic"})," – Application performance monitoring"]}),o("li",{children:[e("strong",{children:"Honeycomb"})," – Observability for complex systems"]})]}),e("p",{className:"text-muted-foreground",children:"You can configure multiple backends and send telemetry to all of them simultaneously."})]}),o("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Sampling and performance"}),e("p",{className:"text-muted-foreground",children:"Collecting telemetry has a cost—CPU, memory, network bandwidth, and storage. ContractSpec provides several mechanisms to control overhead:"}),o("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[o("li",{children:[e("strong",{children:"Sampling"})," – Trace only a percentage of requests (e.g., 10%)"]}),o("li",{children:[e("strong",{children:"Adaptive sampling"})," – Automatically reduce sampling rate under high load"]}),o("li",{children:[e("strong",{children:"Tail-based sampling"})," – Keep traces for failed requests, sample successful ones"]}),o("li",{children:[e("strong",{children:"Field redaction"})," – Remove sensitive data from traces and logs"]}),o("li",{children:[e("strong",{children:"Aggregation"})," – Pre-aggregate metrics before sending to reduce network traffic"]})]})]}),o("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Best practices"}),o("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[e("li",{children:"Start with high-level metrics (request rate, error rate, latency) and add more detailed instrumentation as needed."}),e("li",{children:"Use structured logging—log events with structured fields, not free-form text."}),e("li",{children:"Set up alerts for critical metrics so you're notified when things go wrong."}),e("li",{children:"Use traces to debug complex issues—they show the complete picture of a request."}),e("li",{children:"Redact sensitive data from logs and traces to comply with privacy regulations."}),e("li",{children:"Review dashboards regularly to understand normal behavior—this makes anomalies easier to spot."}),e("li",{children:"Use sampling to control costs, but always trace errors and slow requests."})]})]}),o("div",{className:"flex items-center gap-4 pt-4",children:[e(b,{href:"/docs/advanced/mcp",className:"btn-ghost",children:"Previous: MCP Adapters"}),o(b,{href:"/docs/comparison",className:"btn-primary",children:["Next: Comparison ",e(I,{size:16})]})]})]})}import{jsx as n,jsxs as m}from"react/jsx-runtime";function oe(){return m("div",{className:"space-y-8",children:[m("div",{className:"space-y-4",children:[n("h1",{className:"font-bold text-4xl",children:"Workflow Monitoring"}),n("p",{className:"text-lg text-muted-foreground",children:"Production workflows need robust observability. ContractSpec provides SLA monitoring, distributed tracing, and audit logging out of the box."})]}),m("div",{className:"space-y-4",children:[n("h2",{className:"font-bold text-2xl",children:"SLA Monitoring"}),m("p",{children:["Use the ",n("code",{children:"SLAMonitor"})," to detect when workflows or individual steps exceed their budgeted duration."]}),n("pre",{className:"rounded-lg border bg-muted p-4 text-sm",children:`import { SLAMonitor } from '@contractspec/lib.contracts-spec/workflow/sla-monitor';
|
|
166
166
|
|
|
167
167
|
const monitor = new SLAMonitor((event, payload) => {
|
|
168
168
|
if (event === 'workflow.sla_breach') {
|
|
@@ -172,4 +172,4 @@ const monitor = new SLAMonitor((event, payload) => {
|
|
|
172
172
|
});
|
|
173
173
|
|
|
174
174
|
// Check periodically
|
|
175
|
-
monitor.check(currentState, workflowSpec);`})]}),m("div",{className:"space-y-4",children:[n("h2",{className:"font-bold text-2xl",children:"Telemetry & Tracing"}),n("p",{children:"Workflows automatically generate OpenTelemetry spans for:"}),m("ul",{className:"list-disc space-y-2 pl-6",children:[n("li",{children:"Overall workflow execution"}),n("li",{children:"Individual steps"}),n("li",{children:"Retries and compensation"})]}),n("p",{children:"Configure your OpenTelemetry exporter to send traces to Jaeger, Datadog, or Honeycomb."})]}),m("div",{className:"space-y-4",children:[n("h2",{className:"font-bold text-2xl",children:"Dashboarding"}),m("p",{children:["You can build a custom dashboard using ",n("code",{children:"DataViews"})," over your workflow state database. See the DataViews tutorial for how to visualize ",n("code",{children:"WorkflowState"})," records."]})]})]})}export{
|
|
175
|
+
monitor.check(currentState, workflowSpec);`})]}),m("div",{className:"space-y-4",children:[n("h2",{className:"font-bold text-2xl",children:"Telemetry & Tracing"}),n("p",{children:"Workflows automatically generate OpenTelemetry spans for:"}),m("ul",{className:"list-disc space-y-2 pl-6",children:[n("li",{children:"Overall workflow execution"}),n("li",{children:"Individual steps"}),n("li",{children:"Retries and compensation"})]}),n("p",{children:"Configure your OpenTelemetry exporter to send traces to Jaeger, Datadog, or Honeycomb."})]}),m("div",{className:"space-y-4",children:[n("h2",{className:"font-bold text-2xl",children:"Dashboarding"}),m("p",{children:["You can build a custom dashboard using ",n("code",{children:"DataViews"})," over your workflow state database. See the DataViews tutorial for how to visualize ",n("code",{children:"WorkflowState"})," records."]})]})]})}export{oe as AdvancedWorkflowMonitoringPage,j as AdvancedTelemetryPage,H as AdvancedSpecExperimentsPage,V as AdvancedRenderersPage,Y as AdvancedOverlayEditorPage,U as AdvancedMCPPage};
|