pgkiln 0.70.0 → 0.72.0

package/db/migrations/138_app_utilities.sql

@@ -0,0 +1,153 @@
+-- =====================================================================
+-- 138: an application's Utilities (sprint 138, AP-5; APEX: Application
+--      Utilities: Change History, Attribute Dictionary / UI defaults)
+--
+-- meta.app_snapshot: the application's export (meta.export_app) after the
+--   last recorded change. The builder compares it with a new export after
+--   each change (src/history.ts, the working copies' component split) and
+--   keeps what changed per component in meta.component_change.
+-- meta.component_change: one row per component that a change added,
+--   changed or deleted: its id in the one-file-per-component layout
+--   (src/appfiles.ts, e.g. pages/0003/items/p3_sal), a label, the page,
+--   the component's files before and after ({"path": "text"}), who (a
+--   developer, or null for the command line / MCP server) and when.
+--   Installation data: not exported, kept by import --replace.
+-- meta.ui_default: UI defaults per table column (APEX: Attribute
+--   Dictionary / Table UI Defaults): label, format mask, help, alignment
+--   and list of values. The page wizards and the Create Application wizard
+--   take the label from meta.wizard_column_label (redefined below: a UI
+--   default wins); a form item made by a wizard also gets the column's
+--   format mask, help and list of values (meta.ui_default_item, a trigger
+--   on meta.item that only acts right after meta.wizard_column_label named
+--   a column with a UI default in the same transaction).
+--   Installation data, keyed by schema, table and column names (not oids:
+--   they survive a dump and restore). Not exported with an application.
+-- =====================================================================
+
+create table meta.app_snapshot (
+  app_id   int primary key references meta.app (id) on delete cascade,
+  doc      jsonb not null,
+  taken_at timestamptz not null default now()
+);
+comment on table meta.app_snapshot is
+  'The application''s export after its last recorded change: what the next change is compared with (change history, 138)';
+
+create table meta.component_change (
+  id          bigint generated always as identity primary key,
+  app_id      int not null references meta.app (id) on delete cascade,
+  component   text not null check (length(component) <= 500),
+  label       text not null,
+  page_no     int,
+  op          text not null check (op in ('added', 'changed', 'deleted')),
+  before      jsonb,
+  after       jsonb,
+  changed_by  text,
+  source      text not null default 'builder' check (source in ('builder', 'import', 'upgrade')),
+  changed_at  timestamptz not null default now()
+);
+create index component_change_app_idx on meta.component_change (app_id, changed_at desc);
+create index component_change_component_idx on meta.component_change (app_id, component, changed_at desc);
+comment on table meta.component_change is
+  'Change history per component (138): the component''s files before and after a change, who and when';
+
+create table meta.ui_default (
+  id           int generated always as identity primary key,
+  schema_name  text not null check (schema_name ~ '^[^\s]{1,63}$'),
+  table_name   text not null check (table_name ~ '^[^\s]{1,63}$'),
+  column_name  text not null check (length(column_name) between 1 and 63),
+  label        text check (length(label) <= 200),
+  format_mask  text check (format_mask ~ '^[A-Za-z0-9GDLSCFM.,:/ \-]{1,60}$'),
+  help         text check (length(help) <= 4000),
+  alignment    text check (alignment in ('start', 'center', 'end')),
+  lov          text check (length(lov) <= 4000),
+  updated_by   text,
+  updated_at   timestamptz not null default now(),
+  unique (schema_name, table_name, column_name)
+);
+comment on table meta.ui_default is
+  'UI defaults per table column (APEX: Attribute Dictionary, 138): label, format mask, help, alignment, list of values; used by the page wizards';
+
+-- the UI default of a table's column, or null
+create function meta.ui_default_of(p_table regclass, p_col text) returns meta.ui_default
+language sql stable as $$
+  select d.* from meta.ui_default d
+    join pg_class c on c.oid = p_table join pg_namespace n on n.oid = c.relnamespace
+   where d.schema_name = n.nspname and d.table_name = c.relname and d.column_name = p_col
+$$;
+
+-- (097) a column's label for the generators: (138) its UI default's label wins; a UI default also
+-- tells meta.ui_default_item which column the next wizard item is for (a transaction-local setting)
+create or replace function meta.wizard_column_label(p_table regclass, p_col text) returns text
+language plpgsql stable as $$
+declare
+  v_ui      meta.ui_default := meta.ui_default_of(p_table, p_col);
+  v_comment text;
+  v_rel     text := lower((select relname from pg_class where oid = p_table));
+  v_fk      boolean;
+  v_pk      boolean;
+  v_base    text := p_col;
+  v_rest    text;
+  l         text := lower(p_col);
+begin
+  if v_ui.id is not null then
+    perform set_config('pgkiln.ui_default_col', p_table::oid::text || '.' || p_col, true);
+    if nullif(btrim(v_ui.label), '') is not null then
+      return btrim(v_ui.label);
+    end if;
+  end if;
+  select meta.wizard_short(col_description(p_table, a.attnum), 60) into v_comment
+    from pg_attribute a where a.attrelid = p_table and a.attname = p_col and not a.attisdropped;
+  if v_comment is not null then
+    return v_comment;
+  end if;
+  select c.fk_table is not null, c.is_pk into v_fk, v_pk from meta.wizard_catalog(p_table) c where c.column_name = p_col;
+  if v_fk and not v_pk then
+    v_rest := regexp_replace(p_col, '_?(id|no|num|nr|code|key|fk)$', '', 'i');
+    if length(v_rest) >= 2 then
+      v_base := v_rest;
+    end if;
+  elsif length(l) >= 4 and left(l, 1) = left(v_rel, 1) and not (meta.wizard_abbreviations() ? l) and not meta.wizard_is_word(l)
+        and meta.wizard_is_word(substr(l, 2)) then
+    -- a column named after the table's first letter: ename, dname
+    v_base := substr(p_col, 2);
+  end if;
+  return meta.wizard_label(v_base);
+end
+$$;
+
+-- a form item a wizard is inserting: the column's format mask, help text and list of values
+create function meta.ui_default_item() returns trigger
+language plpgsql as $$
+declare
+  v_mark  text := current_setting('pgkiln.ui_default_col', true);
+  v_table regclass;
+  v_ui    meta.ui_default;
+begin
+  if coalesce(v_mark, '') = '' or new.source_column is null or new.region_id is null then
+    return new;
+  end if;
+  select to_regclass(r.table_name) into v_table from meta.region r where r.id = new.region_id and r.type = 'form';
+  if v_table is null or v_mark <> v_table::oid::text || '.' || new.source_column then
+    return new;
+  end if;
+  perform set_config('pgkiln.ui_default_col', '', true);
+  v_ui := meta.ui_default_of(v_table, new.source_column);
+  if v_ui.id is null or new.type in ('hidden', 'file') then
+    return new;
+  end if;
+  if v_ui.format_mask is not null and new.type in ('number', 'date', 'datetime', 'display', 'text') then
+    new.config := coalesce(new.config, '{}') || jsonb_build_object('format_mask', v_ui.format_mask);
+  end if;
+  if nullif(btrim(v_ui.help), '') is not null then
+    new.help := btrim(v_ui.help);
+  end if;
+  if nullif(btrim(v_ui.lov), '') is not null and new.type in ('text', 'number', 'select') then
+    new.type := 'select';
+    new.lov := btrim(v_ui.lov);
+  end if;
+  return new;
+end
+$$;
+create trigger item_ui_default before insert on meta.item for each row execute function meta.ui_default_item();
+
+revoke all on function meta.ui_default_of(regclass, text), meta.ui_default_item() from public;

package/db/migrations/139_opentelemetry.sql

@@ -0,0 +1,36 @@
+-- =====================================================================
+-- 139: OpenTelemetry (sprint 139, AP-6; APEX: Workspace Utilities →
+--      OpenTelemetry)
+--
+-- The instance's collector and its choices are instance settings in
+-- meta.setting (otel_*: enabled, endpoint, service name, sample ratio,
+-- user attribute, values, signals, builder requests, browser spans;
+-- metrics_endpoint for GET /metrics) and, as only the owner reads it,
+-- meta.instance_setting (otel_headers_enc: headers encrypted with the
+-- instance key; metrics_token_hash), else the standard OTEL_*
+-- environment variables (src/telemetry/config.ts). No table needed.
+--
+-- meta.workspace.telemetry: what the workspace's applications send:
+--   'instance' (the default: the instance's collector, when there is one),
+--   'off' (nothing, not even to the instance's), 'own' (also to the
+--   workspace's own collector, telemetry_endpoint, an OTLP/HTTP base URL
+--   reached through the workspace's network access list and the
+--   installation's allow-list). telemetry_headers_enc: headers for it
+--   (an API key), encrypted like a web credential's secret, write-only.
+--   telemetry_values: send SQL statements with their literals, bind
+--   values, query strings and tool arguments to the own collector.
+--   Installation data: not in the workspace export.
+-- =====================================================================
+
+alter table meta.workspace
+  add column telemetry text not null default 'instance' constraint workspace_telemetry_ok check (telemetry in ('instance', 'off', 'own')),
+  add column telemetry_endpoint text constraint workspace_telemetry_endpoint_ok
+    check (telemetry_endpoint is null or (telemetry_endpoint ~ '^https?://[^\s#@]+$' and length(telemetry_endpoint) <= 500)),
+  add column telemetry_headers_enc text,
+  add column telemetry_values boolean not null default false,
+  add constraint workspace_telemetry_own check (telemetry <> 'own' or telemetry_endpoint is not null);
+
+comment on column meta.workspace.telemetry is 'OpenTelemetry of the workspace''s applications: instance (the instance''s collector), off, own (also its own collector) (139)';
+comment on column meta.workspace.telemetry_endpoint is 'The workspace''s own OTLP/HTTP collector (base URL; /v1/traces and /v1/logs are appended) (139)';
+comment on column meta.workspace.telemetry_headers_enc is 'Headers for the own collector, encrypted with PGKILN_SECRET_KEY (139)';
+comment on column meta.workspace.telemetry_values is 'The own collector also receives values: SQL literals, bind values, query strings (139)';

package/docs/apex-feature-parity.md

@@ -7,13 +7,13 @@ open item and open an issue or pull request; see [CONTRIBUTING.md](../CONTRIBUTI
 Legend: ✅ available · 🟡 partial (see notes) · ❌ not yet · ➖ not planned (a deliberate choice,
 or better served by the PostgreSQL ecosystem; see the notes and [extensions](guide/15-extensions.md))
 
-Last reviewed: 2026-11-03 against **APEX 26.2** (sprint 136: vector providers (an AI service with an embedding model or a SQL function), `meta.embed`, *Add vector column* in Table Properties with an HNSW index and a queue that keeps embeddings current, search types vector and hybrid (reciprocal rank fusion with full-text) and a Retrieve (RAG) tool for AI agents, all as the app's role through RLS, on pgvector (AP-1); sprint 135: full-text search configurations, APEX's Oracle Text search type on PostgreSQL full-text search with stemming, ranking, highlights, *Did you mean* and *Add full-text search* in Table Properties (AP-2); sprint 134: the builder also in Italiano, 中文 (简体), 中文 (繁體), 日本語 and 한국어, APEX's ten builder languages plus Nederlands (SEC-5); sprints 121, 123–125: the builder in Deutsch, English, Español, Français, Nederlands and Português, step by step: the frame, sign-in, Workspace home, App Builder, Page Designer menus, the SQL Workshop's home, SQL Worksheet, Object Browser and Table Properties, Shared Components, application settings, users, identity providers, developers and workspaces (WS-7); sprint 122: *Ask in your own words* sets faceted search and smart filter facets, smart filters read a typed phrase (WS-5), and Sample Maps, Sample Approvals, Sample Data Loading and Sample Files in the App Gallery (WS-8); sprint 120: the App Gallery's single-topic sample apps (charts, cards, calendar, interactive grids, dynamic actions, reporting), the UX Pattern Catalog and a Utility Apps tab with Lookup Lists, Release Notes and Announcements (WS-8); sprint 119: data security per table, a roles × columns matrix and masked values per application role in a masking view, the same identity for pages, AI tools, REST, AutoREST and MCP (WS-13); sprint 118: Administration → Mail queue with delivery per hour and per workspace, the slowest provider calls and failures with Retry and Purge, a workspace's own mail service, and workspace network access lists that narrow the installation's allow-list (WS-9); sprint 117: Pillar Light and Pillar Dark navigation appearances with a header strip, clearer navigation tree states, subtle colour utilities, RTL; sprint 116: the comparison moved from 26.1 to 26.2, with a section for the 26.2 workspace items WS-1 … WS-13 and OCI managed identities; the App Builder list with Updated by, working copies and the lock; `pgkiln import --only`, a file-level import; stale rows on facet menus and blueprints fixed; sprint 115: popup LOVs that load on scroll, Wait Popup dynamic actions and dynamic actions on menu entries; sprint 114: Workflow 26.2 with custom task outcomes, task events and notifications, Send E-Mail and draft steps, migrating running instances and the diagram as SVG / PNG; sprint 113: Team Development with issues, labels, milestones, templates, a board and a set-up wizard; sprint 112: AI interactive reports with chips, Undo, computed columns and a phrase parser that needs no AI service; sprint 111: AI Agents with tools as a shared component, a Navigate tool with checksummed URLs, Gemini and OpenAI-compatible services; sprint 110: Data Reporter as a workspace tool with datasets, reporting applications, editors and viewers, published reports with stable URLs and pins; sprint 109: the Workspace home above the App Builder and SQL Workshop, with a summary, top applications, users and developers, and an optional release check; sprint 108: the code editor's syntax colours in the builder's light and dark themes, read-only SQL highlighted, the Data Modeler in dark mode; sprint 107: a transaction mode in the SQL Worksheet with Commit and Rollback; DA-18: JavaScript (MLE) not planned, plv8 where installed; sprint 106: the change log of DDL change sets with Flyway, Liquibase and SQL downloads; sprint 104: RESTful Services modules, templates and handlers with PL/pgSQL and media handlers, privileges, OpenAPI and Try it; sprint 103: Schema Export / Import with pg_dump and pg_restore; sprint 102: the SQL Monitor with live sessions, Top SQL and a statement's plan; sprint 101: Scheduling of pg_cron jobs with a schedule builder, run now and run history; sprint 100: RESTful Services, tables and views published as REST endpoints with paging, filters, keys and OpenAPI; sprint 99: Administration → Database Users for PostgreSQL roles; sprint 98: the Data Modeler with relational diagrams, DDL and a data dictionary; sprint 97: charts of a query in the worksheet, saved charts and their dashboard; sprint 96: the SQL Workshop's Launchpad with pins and tool groups, the builder's search with Ctrl+K; sprint 95: Table Properties: create, edit or copy a table in a form with a DDL preview and Apply in one transaction; sprint 94: an object's menu with Open in a panel, Quick DDL, Add index / trigger / policy and Drop with dependents; sprint 93: worksheets saved as SQL Scripts with tabs and a Files list, Format, Convert case, find and replace, bind and substitution variables; sprint 92: the worksheet's Query Result with sort, value dialog, copy and downloads, plans as a tree with the slowest step and misestimates, SQL History with status, search and run again; sprint 91: the SQL Worksheet like Database Actions' SQL: navigator, Run Statement at the cursor and Run Script with a log per statement, Explain Plan, Autotrace, notices, history, Run as an application role; sprint 90: Comment Out in the page designer, gallery labels in title case; sprint 89: the Object Browser's schema, one row of tabs, blank NULLs, Modify column; sprint 88: home cards with colour bands and round icons, the hero on the page background, a page footer with the version and Back to top; sprint 87: the Create Application wizard reloads the page list for a schema, RLS badges, the alias from the name; sprint 86: the page designer by page number, HTML error pages in the builder; sprint 85: the Form Designer, beyond APEX; sprint 84: the date picker, facet menus; sprint 83: Component Settings and Component Groups; sprint 82: Report Queries; sprint 81: Application Computations and Shortcuts in Shared Components; sprint 80: the master grid's first row selected when the page opens and after a search; grid cells as text with their format mask until edited, with cell navigation by arrow keys, Enter, F2 and Escape; sprint 79: generated dashboards with sums, donuts and lines, leaving out charts that say nothing; applications open in their own light or dark mode until the user chooses, per application; a user menu with Appearance and Sign in when signed out; the developer toolbar's App and Page texts and debug state; the report search's column scope in the magnifier; sprint 78: generated faceted search reports with one column per foreign key, the faceted search's total row count, Show all and Yes/No values, one search field, friendly headings and number formats in generated grids and master-detail pages, friendly names in the Create Application wizard's page list; sprint 77: the Page Designer's layout and tree by display position, button positions, the tree's context menu with Duplicate and Copy to other page, Show Common / Show All, Go to group and the Template Options dialog; display positions, button positions and side-column page templates at runtime; sprint 76: the interactive report's menus and pagination, date items in the date format; sprint 75: the SQL Workshop's Object Browser and tabs; sprint 74: the builder's information architecture: Shared Components grid, Settings tabs, application home search and tasks; sprint 73: the Create Application wizard on one page with page types and features; sprint 72: the runtime chrome compared with APEX 26.2's: the developer toolbar, the Iris look, the navigation bar's Help menu and Install button; sprint 71: generated applications compared with APEX 26.2's: labels, foreign key names in reports, file columns, format masks, the Home page and the dashboard; sprint 70: treemap, sunburst and timeline charts; sprint 69: dragging tasks on a Gantt chart; sprint 68: the Data Reporter's welcome page, Find my workspace; sprint 67: REST source catalogs from OpenAPI documents, a workspace's export and import (two rows added); sprint 66: a blueprint from an existing application; sprint 65: facet charts; sprint 64: approval vacation rules and expiration policies; sprint 63: range, box plot and stock charts; sprint 62: workspace preferences (SQL Workshop and RESTful services per workspace), extension links, Manage backups across applications, SQL Workshop utilities with object reports, About Database and a database monitor; sprint 61: the builder's screens compared with APEX 26.1: the workspace sign-in page, the Administration menu with workspace message, environment banner and utilization, the SQL Workshop home, the App Gallery, application groups and cross application reports (four rows added); sprint 60: isolated workspaces with their own database logins, row-level security on pgkiln's tables and workspace database roles, workspace administrators; sprint 59: the Page Designer's help pane, Quick edit from the developer toolbar; sprint 58: page groups; sprint 57: region templates hero, title bar, buttons container, inline dialog and drawer, wizard with wizard progress, the carousel; sprint 56: Generate DDL and Schema Comparison in the SQL Workshop, `pgkiln ddl` and `pgkiln compare`; sprint 55: an editable login page with a Login region and the Minimal page template, Forgot password through the application's mail service; sprint 54: interactive grid views, the single row view, group by and chart; sprint 53: application settings, user preferences and items kept per user, dynamic translations, `meta.data_export` and data export downloads, display image and geocoded address items; sprint 52: every dynamic action event and action, Ajax callbacks, an error handling function, the session timeout warning; sprint 51: checked imports, application backups, availability and Run only, feedback, type-specific attribute help; sprint 50: lost update detection, warn on unsaved changes, the URL and search regions with search configurations, the developer toolbar with a session state viewer, and e-mail through SMTP with OAuth2, Microsoft Graph, Amazon SES and HTTP APIs; import checks, application availability, property help and e-mail compared again; 2026-10-06: pgkiln 0.31.0, in progress: static application files and the Execute JavaScript dynamic action; region, item, dynamic action and process plug-ins; conditional and dynamic theme styles; XML and Excel in `meta.parse_data`, zips in SQL, `meta.v_boolean`; file items in S3-compatible object storage; map layers by the visible area and as vector tiles; a graphical query builder; tenants for workflows and tasks; application files as YAML and region static IDs; Lucide icons and icon modifiers; PWA push notifications; 0.30.0: 136 icons and an icon picker; an axe-core accessibility audit; cropping pictures; session sharing between applications; twenty-two built-in languages; 0.29.0: workspaces; the Iris base style; drawers; built-in template components including the metric card; Theme Roller dark-mode colours, live preview and template options on items and report columns; report selection across pages; instance settings; fourteen built-in languages; 0.28.0: AI with Claude and OpenAI; 0.27.0: Data Reporter; sample data generator; create application from several sheets, pasted data or existing tables; 0.26.0: working copies with a three-way merge; theme, library and boilerplate applications with subscriptions; 0.25.0: Gantt, pyramid and polar charts; map layers, clustering and server-side spatial filters; REST data sources that write back from forms and grids and synchronise into tables, OAuth2 password and refresh-token grants; debug messages per request and an install/upgrade log; `meta.web_request()` and `meta.parse_data()`; Theme Roller style variants and template options; 0.24.0: automations with several actions, error handling per row and runs from SQL; invoke-API workflow steps; Unload Data in the Data Workshop; create page wizards for cards, calendar, chart, map, faceted search, form and master-detail; create an application from a file; 0.23.0: interactive grid aggregates, frozen/moved/resized columns, layouts and saved grid reports, master-detail, row actions and copy/paste; download processes, execution chains in the background, workflow processes, branches to a function's URL or another app, the Dialog Closed event; number format masks, automatic time zone, runtime messages in German, French and Spanish; SQL scripts, Quick SQL, a query builder, XML loading and data load definitions; custom authentication, lists, page and application locks with developer comments, supporting objects; 0.22.0: keyset paging, report PDFs and REST collections streamed from a cursor, database-account authentication; 0.21.0: HTTP-header authentication behind a reverse proxy; 0.20.0: a popup list of values with server-side search; 0.19.0: row-range pagination, maximum row counts and row limits, lazy loading and caching of regions, streamed CSV/Excel downloads; 0.18.0: calendar week/day/list views with drag and drop, bubble/gauge/funnel/radar charts and drill-down, smart filters, a region display selector and more facet types, computations, conditional branches, build options, menu buttons, REST data sources and web credentials, rich text/Markdown, rating, combobox, date range and QR code items; 0.17.0: an App Builder home, workspace dashboard and utilities like APEX's; 0.16.0: a Page Designer with drag-and-drop layout, a code editor with autocomplete, template components and plug-ins, parallel branches and versions of workflows, the `pgkiln` command line with one file per component; 0.15.0: drop and paste files, heat maps, filtering a report by the map area; 0.14.0: stacked, combo, scatter and pie charts, several files per upload item; 0.13.0: map and tree regions; 0.12.0: REST modules in the builder; 0.11.0: workflows and Progressive Web Apps; 0.10.0: LDAP, SAML, "Keep me signed in", document templates, JSON loading, approvals and the task list; pgkiln installs no application, HR is an example).
+Last reviewed: 2026-11-04 against **APEX 26.2** (sprint 139: OpenTelemetry, traces with a span per SQL statement, web call, AI request and tool call, logs, metrics and `/metrics` for Prometheus, browser spans relayed by pgkiln, per workspace off or its own collector (AP-6); sprint 138: an application's Utilities tab with a dashboard, database object dependencies, change history per component, Upgrade application, UI defaults (APEX's Attribute Dictionary), application and page checksums and an icon browser (AP-5); sprint 137: Create page as a grid of page types with previews, the page types interactive report, smart filters, search page, data loading, tree, timeline, media list, content row, comments, dashboard, wizard, unified task list and workflow console, a Feature tab with nine features that install once, and Create page as copy with shared components mapped or copied (AP-3); sprint 136: vector providers (an AI service with an embedding model or a SQL function), `meta.embed`, *Add vector column* in Table Properties with an HNSW index and a queue that keeps embeddings current, search types vector and hybrid (reciprocal rank fusion with full-text) and a Retrieve (RAG) tool for AI agents, all as the app's role through RLS, on pgvector (AP-1); sprint 135: full-text search configurations, APEX's Oracle Text search type on PostgreSQL full-text search with stemming, ranking, highlights, *Did you mean* and *Add full-text search* in Table Properties (AP-2); sprint 134: the builder also in Italiano, 中文 (简体), 中文 (繁體), 日本語 and 한국어, APEX's ten builder languages plus Nederlands (SEC-5); sprints 121, 123–125: the builder in Deutsch, English, Español, Français, Nederlands and Português, step by step: the frame, sign-in, Workspace home, App Builder, Page Designer menus, the SQL Workshop's home, SQL Worksheet, Object Browser and Table Properties, Shared Components, application settings, users, identity providers, developers and workspaces (WS-7); sprint 122: *Ask in your own words* sets faceted search and smart filter facets, smart filters read a typed phrase (WS-5), and Sample Maps, Sample Approvals, Sample Data Loading and Sample Files in the App Gallery (WS-8); sprint 120: the App Gallery's single-topic sample apps (charts, cards, calendar, interactive grids, dynamic actions, reporting), the UX Pattern Catalog and a Utility Apps tab with Lookup Lists, Release Notes and Announcements (WS-8); sprint 119: data security per table, a roles × columns matrix and masked values per application role in a masking view, the same identity for pages, AI tools, REST, AutoREST and MCP (WS-13); sprint 118: Administration → Mail queue with delivery per hour and per workspace, the slowest provider calls and failures with Retry and Purge, a workspace's own mail service, and workspace network access lists that narrow the installation's allow-list (WS-9); sprint 117: Pillar Light and Pillar Dark navigation appearances with a header strip, clearer navigation tree states, subtle colour utilities, RTL; sprint 116: the comparison moved from 26.1 to 26.2, with a section for the 26.2 workspace items WS-1 … WS-13 and OCI managed identities; the App Builder list with Updated by, working copies and the lock; `pgkiln import --only`, a file-level import; stale rows on facet menus and blueprints fixed; sprint 115: popup LOVs that load on scroll, Wait Popup dynamic actions and dynamic actions on menu entries; sprint 114: Workflow 26.2 with custom task outcomes, task events and notifications, Send E-Mail and draft steps, migrating running instances and the diagram as SVG / PNG; sprint 113: Team Development with issues, labels, milestones, templates, a board and a set-up wizard; sprint 112: AI interactive reports with chips, Undo, computed columns and a phrase parser that needs no AI service; sprint 111: AI Agents with tools as a shared component, a Navigate tool with checksummed URLs, Gemini and OpenAI-compatible services; sprint 110: Data Reporter as a workspace tool with datasets, reporting applications, editors and viewers, published reports with stable URLs and pins; sprint 109: the Workspace home above the App Builder and SQL Workshop, with a summary, top applications, users and developers, and an optional release check; sprint 108: the code editor's syntax colours in the builder's light and dark themes, read-only SQL highlighted, the Data Modeler in dark mode; sprint 107: a transaction mode in the SQL Worksheet with Commit and Rollback; DA-18: JavaScript (MLE) not planned, plv8 where installed; sprint 106: the change log of DDL change sets with Flyway, Liquibase and SQL downloads; sprint 104: RESTful Services modules, templates and handlers with PL/pgSQL and media handlers, privileges, OpenAPI and Try it; sprint 103: Schema Export / Import with pg_dump and pg_restore; sprint 102: the SQL Monitor with live sessions, Top SQL and a statement's plan; sprint 101: Scheduling of pg_cron jobs with a schedule builder, run now and run history; sprint 100: RESTful Services, tables and views published as REST endpoints with paging, filters, keys and OpenAPI; sprint 99: Administration → Database Users for PostgreSQL roles; sprint 98: the Data Modeler with relational diagrams, DDL and a data dictionary; sprint 97: charts of a query in the worksheet, saved charts and their dashboard; sprint 96: the SQL Workshop's Launchpad with pins and tool groups, the builder's search with Ctrl+K; sprint 95: Table Properties: create, edit or copy a table in a form with a DDL preview and Apply in one transaction; sprint 94: an object's menu with Open in a panel, Quick DDL, Add index / trigger / policy and Drop with dependents; sprint 93: worksheets saved as SQL Scripts with tabs and a Files list, Format, Convert case, find and replace, bind and substitution variables; sprint 92: the worksheet's Query Result with sort, value dialog, copy and downloads, plans as a tree with the slowest step and misestimates, SQL History with status, search and run again; sprint 91: the SQL Worksheet like Database Actions' SQL: navigator, Run Statement at the cursor and Run Script with a log per statement, Explain Plan, Autotrace, notices, history, Run as an application role; sprint 90: Comment Out in the page designer, gallery labels in title case; sprint 89: the Object Browser's schema, one row of tabs, blank NULLs, Modify column; sprint 88: home cards with colour bands and round icons, the hero on the page background, a page footer with the version and Back to top; sprint 87: the Create Application wizard reloads the page list for a schema, RLS badges, the alias from the name; sprint 86: the page designer by page number, HTML error pages in the builder; sprint 85: the Form Designer, beyond APEX; sprint 84: the date picker, facet menus; sprint 83: Component Settings and Component Groups; sprint 82: Report Queries; sprint 81: Application Computations and Shortcuts in Shared Components; sprint 80: the master grid's first row selected when the page opens and after a search; grid cells as text with their format mask until edited, with cell navigation by arrow keys, Enter, F2 and Escape; sprint 79: generated dashboards with sums, donuts and lines, leaving out charts that say nothing; applications open in their own light or dark mode until the user chooses, per application; a user menu with Appearance and Sign in when signed out; the developer toolbar's App and Page texts and debug state; the report search's column scope in the magnifier; sprint 78: generated faceted search reports with one column per foreign key, the faceted search's total row count, Show all and Yes/No values, one search field, friendly headings and number formats in generated grids and master-detail pages, friendly names in the Create Application wizard's page list; sprint 77: the Page Designer's layout and tree by display position, button positions, the tree's context menu with Duplicate and Copy to other page, Show Common / Show All, Go to group and the Template Options dialog; display positions, button positions and side-column page templates at runtime; sprint 76: the interactive report's menus and pagination, date items in the date format; sprint 75: the SQL Workshop's Object Browser and tabs; sprint 74: the builder's information architecture: Shared Components grid, Settings tabs, application home search and tasks; sprint 73: the Create Application wizard on one page with page types and features; sprint 72: the runtime chrome compared with APEX 26.2's: the developer toolbar, the Iris look, the navigation bar's Help menu and Install button; sprint 71: generated applications compared with APEX 26.2's: labels, foreign key names in reports, file columns, format masks, the Home page and the dashboard; sprint 70: treemap, sunburst and timeline charts; sprint 69: dragging tasks on a Gantt chart; sprint 68: the Data Reporter's welcome page, Find my workspace; sprint 67: REST source catalogs from OpenAPI documents, a workspace's export and import (two rows added); sprint 66: a blueprint from an existing application; sprint 65: facet charts; sprint 64: approval vacation rules and expiration policies; sprint 63: range, box plot and stock charts; sprint 62: workspace preferences (SQL Workshop and RESTful services per workspace), extension links, Manage backups across applications, SQL Workshop utilities with object reports, About Database and a database monitor; sprint 61: the builder's screens compared with APEX 26.1: the workspace sign-in page, the Administration menu with workspace message, environment banner and utilization, the SQL Workshop home, the App Gallery, application groups and cross application reports (four rows added); sprint 60: isolated workspaces with their own database logins, row-level security on pgkiln's tables and workspace database roles, workspace administrators; sprint 59: the Page Designer's help pane, Quick edit from the developer toolbar; sprint 58: page groups; sprint 57: region templates hero, title bar, buttons container, inline dialog and drawer, wizard with wizard progress, the carousel; sprint 56: Generate DDL and Schema Comparison in the SQL Workshop, `pgkiln ddl` and `pgkiln compare`; sprint 55: an editable login page with a Login region and the Minimal page template, Forgot password through the application's mail service; sprint 54: interactive grid views, the single row view, group by and chart; sprint 53: application settings, user preferences and items kept per user, dynamic translations, `meta.data_export` and data export downloads, display image and geocoded address items; sprint 52: every dynamic action event and action, Ajax callbacks, an error handling function, the session timeout warning; sprint 51: checked imports, application backups, availability and Run only, feedback, type-specific attribute help; sprint 50: lost update detection, warn on unsaved changes, the URL and search regions with search configurations, the developer toolbar with a session state viewer, and e-mail through SMTP with OAuth2, Microsoft Graph, Amazon SES and HTTP APIs; import checks, application availability, property help and e-mail compared again; 2026-10-06: pgkiln 0.31.0, in progress: static application files and the Execute JavaScript dynamic action; region, item, dynamic action and process plug-ins; conditional and dynamic theme styles; XML and Excel in `meta.parse_data`, zips in SQL, `meta.v_boolean`; file items in S3-compatible object storage; map layers by the visible area and as vector tiles; a graphical query builder; tenants for workflows and tasks; application files as YAML and region static IDs; Lucide icons and icon modifiers; PWA push notifications; 0.30.0: 136 icons and an icon picker; an axe-core accessibility audit; cropping pictures; session sharing between applications; twenty-two built-in languages; 0.29.0: workspaces; the Iris base style; drawers; built-in template components including the metric card; Theme Roller dark-mode colours, live preview and template options on items and report columns; report selection across pages; instance settings; fourteen built-in languages; 0.28.0: AI with Claude and OpenAI; 0.27.0: Data Reporter; sample data generator; create application from several sheets, pasted data or existing tables; 0.26.0: working copies with a three-way merge; theme, library and boilerplate applications with subscriptions; 0.25.0: Gantt, pyramid and polar charts; map layers, clustering and server-side spatial filters; REST data sources that write back from forms and grids and synchronise into tables, OAuth2 password and refresh-token grants; debug messages per request and an install/upgrade log; `meta.web_request()` and `meta.parse_data()`; Theme Roller style variants and template options; 0.24.0: automations with several actions, error handling per row and runs from SQL; invoke-API workflow steps; Unload Data in the Data Workshop; create page wizards for cards, calendar, chart, map, faceted search, form and master-detail; create an application from a file; 0.23.0: interactive grid aggregates, frozen/moved/resized columns, layouts and saved grid reports, master-detail, row actions and copy/paste; download processes, execution chains in the background, workflow processes, branches to a function's URL or another app, the Dialog Closed event; number format masks, automatic time zone, runtime messages in German, French and Spanish; SQL scripts, Quick SQL, a query builder, XML loading and data load definitions; custom authentication, lists, page and application locks with developer comments, supporting objects; 0.22.0: keyset paging, report PDFs and REST collections streamed from a cursor, database-account authentication; 0.21.0: HTTP-header authentication behind a reverse proxy; 0.20.0: a popup list of values with server-side search; 0.19.0: row-range pagination, maximum row counts and row limits, lazy loading and caching of regions, streamed CSV/Excel downloads; 0.18.0: calendar week/day/list views with drag and drop, bubble/gauge/funnel/radar charts and drill-down, smart filters, a region display selector and more facet types, computations, conditional branches, build options, menu buttons, REST data sources and web credentials, rich text/Markdown, rating, combobox, date range and QR code items; 0.17.0: an App Builder home, workspace dashboard and utilities like APEX's; 0.16.0: a Page Designer with drag-and-drop layout, a code editor with autocomplete, template components and plug-ins, parallel branches and versions of workflows, the `pgkiln` command line with one file per component; 0.15.0: drop and paste files, heat maps, filtering a report by the map area; 0.14.0: stacked, combo, scatter and pie charts, several files per upload item; 0.13.0: map and tree regions; 0.12.0: REST modules in the builder; 0.11.0: workflows and Progressive Web Apps; 0.10.0: LDAP, SAML, "Keep me signed in", document templates, JSON loading, approvals and the task list; pgkiln installs no application, HR is an example).
 
 ## At a glance
 
 | Area | ✅ | 🟡 | ❌ | ➖ | In short |
 |---|---:|---:|---:|---:|---|
-| App Builder and development | 21 | 0 | 0 | 0 | Page Designer with drag-and-drop and a code editor, wizards, search, where used, an Advisor, a CLI with one file per component, page locks and comments, supporting objects, working copies with a three-way merge, theme/library/boilerplate apps with subscriptions; App Builder AI (pages, SQL and table descriptions) |
+| App Builder and development | 22 | 0 | 0 | 0 | Page Designer with drag-and-drop and a code editor, wizards, search, where used, an Advisor, a CLI with one file per component, page locks and comments, supporting objects, working copies with a three-way merge, theme/library/boilerplate apps with subscriptions; App Builder AI (pages, SQL and table descriptions) |
 | Regions | 23 | 0 | 0 | 0 | All everyday regions, a search region over search configurations and a URL region; twenty-two chart types with drill-down; calendars with week/day/list views and drag and drop; faceted search, smart filters and a region display selector; interactive reports with breaks, aggregates, highlights, compute, group by, pivot, chart view and saved reports; interactive grids with single row, group by and chart views; maps (with vector tiles) and trees; template components; row ranges, lazy loading and region caching for large tables |
 | Items | 13 | 0 | 0 | 0 | All common items, file upload (several files per item), rich text and Markdown editors, star rating, combobox, date range, QR code, password reveal, display image and geocoded address |
 | Logic and processing | 18 | 0 | 0 | 1 | User preferences and application settings; all dynamic action events and actions, Ajax callbacks and an error handling function; Core APEX model complete with computations, conditional branches, build options and menu buttons, download, chain and workflow processes; JavaScript from static application files in dynamic actions; region, item, dynamic action and process plug-ins |
@@ -22,9 +22,9 @@ Last reviewed: 2026-11-03 against **APEX 26.2** (sprint 136: vector providers (a
 | Globalization | 6 | 0 | 0 | 0 | One translated app like 26.1 with dynamic translations of table values; number format masks and automatic time zone; twenty-two built-in languages |
 | Data and integration | 13 | 0 | 0 | 2 | REST source catalogs from OpenAPI documents; Generate DDL and schema comparison; `meta.data_export` and data export downloads (CSV, JSON, XML, HTML, Excel, PDF); e-mail through SMTP (password or OAuth2), Microsoft Graph, Amazon SES and HTTP APIs; REST APIs via PostgREST, REST data sources that write back and synchronise, web credentials with OAuth2 grants, CSV/XLSX/JSON/XML loading with saved definitions and unloading, SQL scripts and Quick SQL, report PDFs and document templates |
 | Workflow, automation and AI | 6 | 0 | 0 | 0 | Scheduled automations with several actions and runs from SQL, approvals, a task list and workflows with parallel branches, versions and invoke-API steps; AI with Claude or OpenAI: *Generate text with AI*, an assistant region with tools, natural-language report filters and blueprints |
-| Administration | 14 | 0 | 0 | 0 | An APEX-like sign-in with a workspace and a Workspace home; a mail queue dashboard, a workspace's own mail service and network access list (26.1 / 26.2); a workspace's components exported and imported as one file; workspace message, environment banner and utilization; isolated workspaces with their own database logins and roles, and workspace administrators; application availability and Run only, automatic backups, user feedback; a developer toolbar with a session state viewer and debug per session; Top SQL per app; debug messages per request; an install/upgrade log |
+| Administration | 15 | 0 | 0 | 0 | OpenTelemetry traces, logs and metrics to the team's own monitoring and `/metrics` for Prometheus (24.2); An APEX-like sign-in with a workspace and a Workspace home; a mail queue dashboard, a workspace's own mail service and network access list (26.1 / 26.2); a workspace's components exported and imported as one file; workspace message, environment banner and utilization; isolated workspaces with their own database logins and roles, and workspace administrators; application availability and Run only, automatic backups, user feedback; a developer toolbar with a session state viewer and debug per session; Top SQL per app; debug messages per request; an install/upgrade log |
 | APEX 26.2 workspace (WS-1 … WS-13) | 13 | 0 | 0 | 1 | Workspace home, Data Reporter as a workspace tool, Team Development, AI Agents, AI interactive reports, Workflow 26.2, the mail queue, workspace mail and network access, the 26.1 component details, the App Builder list's details, the Pillar navigation appearances and data security per table (rows, columns and masked values), the App Gallery's single-topic sample apps, UX Pattern Catalog and Utility Apps; the builder in eleven languages (APEX's ten and Nederlands) |
-| **Total** | **161** | **0** | **0** | **4** | 165 APEX features compared: 98% available, none missing, 4 deliberately not planned |
+| **Total** | **163** | **0** | **0** | **4** | 167 APEX features compared: 98% available, none missing, 4 deliberately not planned |
 
 (Counts are of the rows in the tables below. A review on 2026-10-06 added 18 rows for APEX features that were
 not compared before, one on 2026-10-12 added two more (property help, application availability), and one on
@@ -33,7 +33,7 @@ application reports, Manage Service), so the share available dropped without any
 two, REST source catalogs and the workspace export, with their features. Sprint 116 compared with APEX 26.2 and added
 the section [APEX 26.2 workspace](#apex-262-workspace-ws-1--ws-13): fourteen rows, the 26.2 workspace items WS-1 … WS-13
 and OCI managed identities. Some of them repeat a row above from the workspace's side; they are counted on purpose, as
-the 26.2 comparison.)
+the 26.2 comparison. Sprint 139 added OpenTelemetry (24.2), found missing by the 27 Oct pass (AP-6).)
 
 ## App Builder and development
 
@@ -41,7 +41,7 @@ the 26.2 comparison.)
 |---|---|---|
 | App Builder: create, edit, delete, run apps | ✅ | Builder at `/builder` |
 | Create application wizard | ✅ | Blank app with its own database role and schema, started from a **boilerplate application** if wanted; **from a file**: CSV/TSV/XLSX/JSON/XML, where an Excel workbook with several sheets (or JSON with several arrays) becomes several tables, with a preview to include or leave out each sheet, edit table/column names, types and primary keys, and **foreign keys proposed** from matching columns; **from pasted data** (CSV/TSV text); **from existing tables** (pick the tables and views of a schema). Each gives a report and form per table, navigation and an optional dashboard (a chart per table), plus an optional faceted search for a single table, all created in one transaction. (sprint 73) **One page like APEX's**: name, icon and description, appearance (theme style, side or top menu, accent), a **page type per table** (interactive report with form, faceted search, cards, calendar, master detail, interactive grid, report, none; large tables proposed as a grid), **features** (About page, access control roles, activity reporting, feedback, theme style selection, PWA, push), settings (alias, authentication, first user, language) and a boilerplate under Advanced; a progress message, then straight to the new application. (sprint 71) The generated pages read like APEX's: human labels (abbreviations, run-together words, column and table comments), plural page and menu names with singular form titles, foreign keys shown by the parent's name in reports, `bytea` columns as one file item with their name/mime/size/updated columns, number format masks, a pencil per report row, the Dashboard after Home with *(none)* and top-N charts, and a Home page with a hero and a card per page. (sprint 66) **From a blueprint** (26.1 blueprints): a reviewed JSON spec of tables, pages and sample data, or a blueprint made from an existing application (see [Blueprints](#workflow-automation-and-ai)) |
-| Create page wizards | ✅ | Report and form, interactive grid, form, cards, calendar, chart, map, faceted search and master-detail (stacked grids) from any table or view, with defaults from the catalog (columns, key, dates, positions, foreign keys), an optional modal form page and a navigation entry; also from SQL (`meta.generate_page`). No side-by-side or drill-down master-detail, no wizard for smart filters or trees |
+| Create page wizards, Create a Page (Component, Feature), Create Page as Copy | ✅ | (sprint 137, AP-3) **Create page** is a grid of page types with small previews like APEX's: Blank page, Calendar, Cards, Chart, Comments, Content row, Dashboard, Data loading, Faceted search, Form, Interactive grid, Interactive report, Map, Master detail, Media list, Report and form, Search page, Smart filters, Timeline, Tree, Unified task list, Wizard, Workflow console and Create pages with AI; the table step only for the types on a table, with defaults from the catalog (columns, key, dates, positions, foreign keys; a tree's parent from a self-referencing foreign key; a wizard's steps with a progress list; a data load definition and its page), an optional modal form page and a navigation entry; also from SQL (`meta.generate_page`). **Feature** (also App home → Add feature page): Access control, Activity reporting, Configuration options (configurable build options as switches for administrators), E-mail reporting (a weekly activity report by mail), Feedback, About, Login page, Theme style selection, Push notifications; each lists what it adds, installs once and greys out ([chapter 3](guide/03-builder.md#add-feature)). **Copy**: a page of this or another application of the workspace under a new number and name, `P<n>_` items renamed, the shared components it uses mapped to the target's or copied ([chapter 3](guide/03-builder.md#create-page-as-copy)). No Classic Report type (the interactive report covers it), no side-by-side or drill-down master-detail
 | Page Designer | ✅ | IDE-style window (dark or light): component tree, a layout canvas with drag and drop (with keyboard and button alternatives) and a gallery of regions, items and buttons, a filterable property editor; undo/redo; panes become tabs on phones. Settings forms for report, grid, chart, cards, calendar, faceted search, smart filters, display selector, map, tree and template component regions. A code editor for SQL, PL/pgSQL, JSON and HTML with highlighting and autocomplete of tables, columns and `:ITEM` binds (no extra libraries). Drag and drop needs a mouse; on touch screens the Arrange buttons move components. (sprint 77) The layout draws the page template's display positions (banner, breadcrumb bar, left/right column, body, footer) as drop zones and a region's button positions; the rendering tree groups by position and has a context menu (create in or below, Duplicate, Copy to other page, expand/collapse all, (sprint 90) Comment out with a COMMENTED_OUT build option, delete; no Create Sub Region: no nested regions); the property editor has Common / All, Go to group and a Template Options dialog; a page number in the toolbar. No nested regions (APEX's sub regions) |
 | Shared components | ✅ | (sprint 74) A grid of ten groups with counts like APEX's, a searchable, sortable list per type with Create, and Settings-backed types linking to their Settings tab ([mapping below](#shared-components-apex-links-and-pgkiln)). Navigation menu, **lists** (static entries with nesting, badges, conditions, authorization and build options, or a query; for list regions, the navigation menu and the navigation bar), authorization schemes, build options, lists of values, application items and processes, access control, globalization, template components and plug-ins, web credentials, REST data sources, data load definitions, supporting objects |
 | Export / import | ✅ | `meta.export_app()` / `meta.import_app()`: portable JSON, also in the builder (new applications; `pgkiln import --replace` and the MCP `import_app` update one in place, live for every user at the commit). (sprint 51) **Checked imports**: `pgkiln import --check` (`--dry-run`, `--force`), the MCP import (by default) and the builder's import run the Advisor inside the import's transaction (SQL planned as the application's role: missing tables, columns, functions, types, grants; references) and refuse on errors, so nothing changes; APEX doesn't check. The version an import replaces is [backed up](guide/03-builder.md#backups) first ([chapter 18](guide/18-cli.md#checking-before-an-import)) |
@@ -54,6 +54,7 @@ the 26.2 comparison.)
 | Theme, library and boilerplate application types (26.1) | ✅ | An application type in Settings ([chapter 3](guide/03-builder.md#application-types-and-subscriptions)): a **theme** app offers its theme (colours, navigation, Theme Roller styles) and template components, a **library** app its lists of values, authorization schemes, build options, template components and lists; other apps **subscribe** (the component is copied), see whether they are in sync, **refresh** one or all, and the master **publishes** to its subscribers (locked apps skipped). A **boilerplate** app is a *Start from* choice in Create application. Subscriptions are not exported; no subscriptions to pages or plug-ins other than template components |
 | Property help in the Page Designer, component reference | ✅ | Help text under most properties in the Page Designer (175 of 266 fields; the obvious ones such as *Title* and *Sequence* have none), and a guide section per region type, item type and button with the columns its SQL must return ([chapter 4](guide/04-pages-and-regions.md#region-types), [5](guide/05-items.md), [6](guide/06-processing.md#buttons)). (sprint 51) A region's *Attributes (JSON)* help shows its own type's keys with a link to its section of the guide. (sprint 59) The **Help pane** under the properties shows the focused property's help, the name it is stored under and the guide section of the component's type |
 | Advisor | ✅ | Per app: every SQL fragment planned (EXPLAIN, as the app's role, rolled back) for syntax, unknown objects, types and grants; PL/pgSQL blocks compiled; references to missing pages, items, lists of values, schemes and layouts; PL/pgSQL functions with `plpgsql_check` when installed. Plus the security checklist |
+| Application Utilities: dashboard, database object dependencies, change history, Upgrade Application, Attribute Dictionary, application and page checksums, icons | ✅ | (sprint 138, AP-5) An application's **Utilities** tab gathers the Advisor, Search, Debug, Activity, Backups, Working copies and Export with an application dashboard and recently updated pages; **Database object dependencies** (every SQL the Advisor plans, parsed as the app's role, with the components that use each object; missing objects and missing grants in red); **Change history** per component with who, when and a diff, for builder changes and every import `--replace` (`CHANGE_HISTORY_DAYS`); **Upgrade application** (date pickers for date columns, popup LOVs for large tables, a navigation appearance) with a preview; **UI defaults** per column (label, format mask, help, alignment, LOV) used by the page and application wizards, seeded from column comments; a SHA-256 **application checksum** with one per page, also in Export's `X-Pgkiln-Checksum` header; an **icon browser** ([chapter 3](guide/03-builder.md#utilities)) |
 | Builder search, "where used" | ✅ | Search over every page and component (names, SQL, settings, help); "Used in" under items, pages, lists of values, schemes and report layouts. No search and replace |
 | AI assistant, pages from natural language, describe tables for LLMs (26.1) | ✅ | **App Builder AI** (administrators choose the builder's AI service): SQL Workshop → AI writes SQL from a question (shown in an editor, never run automatically), explains a query or an error, and describes tables and columns for LLMs (notes, optionally `COMMENT ON`, with AI drafts from names, types and keys only); **Create pages with AI** turns a description into proposed pages that the developer edits and confirms ([chapter 3](guide/03-builder.md)). The model never sees table rows |
 | Sample data source for development (26.1) | ✅ | SQL Workshop → **Sample Data** ([chapter 16](guide/16-files.md#sql-workshop--sample-data)): generators proposed per column from the catalog and column names (names, e-mail addresses, phones, companies, addresses, words and sentences, codes, number/date/time ranges, booleans, value lists from enums and CHECKs, sequences, foreign keys picking existing or newly inserted parent rows, values relative to another column, % nulls; identity/serial/generated columns skipped; unique and simple CHECK constraints respected), rows per table, a seed for repeatable data, preview (inserted and rolled back), insert in one transaction with parents first, download as SQL INSERTs or CSV, saved generator definitions |
@@ -81,7 +82,7 @@ the 26.2 comparison.)
 | Region display selector, tabs | ✅ | Tabs or a select list; regions can share a tab, *Show all*, the choice remembered in the session, `#R<id>` links. Accessible tabs with JavaScript; without it every region shows with links to each |
 | Tree | ✅ | `tree` region from id / parent id / label rows, with icons, links and the first levels open; works without JavaScript |
 | Map region (26.1: vector tiles, bounding box) | ✅ | `map` region: several layers per map, each with its own query (markers, lines and areas from GeoJSON or a PostGIS geometry, heat maps), a legend that switches layers on and off and a colour per layer; marker clustering; popups with links. A report can be filtered by the visible area or by the distance from the map's centre on the server: with PostGIS (`ST_Intersects`/`ST_DWithin`, detected automatically) when installed, otherwise on latitude/longitude (bounding box, haversine). Configurable tile server. (0.31) **Large data sets**: a layer loads only the places in the visible area, again as the map moves (`visible_area`), or is served as **Mapbox Vector Tiles** (`tiles`, MVT 2.1, drawn on canvases with popups; readable by MapLibre, OpenLayers or QGIS), both filtered on the server like the report filter ([chapter 4](guide/04-pages-and-regions.md#map)) |
-| Timeline, comments, media list, avatar template components (26.1: groups, Metric Card) | ✅ | Built in for every application: avatar (groups), badge, comments, media list, metric card and timeline, as regions (one or all rows, the group) and report column templates; an application's own copy replaces a built-in one ([chapter 4](guide/04-pages-and-regions.md#built-in-template-components)) |
+| Timeline, comments, media list, avatar template components (26.1: groups, Metric Card) | ✅ | Built in for every application: avatar (groups), badge, comments, (sprint 137) content row, media list, metric card and timeline, as regions (one or all rows, the group) and report column templates; an application's own copy replaces a built-in one ([chapter 4](guide/04-pages-and-regions.md#built-in-template-components)) |
 | Pagination of large tables (row ranges, maximum row count) | ✅ | Reports and grids page in the database; `"pagination": "range"` shows APEX's "row ranges X to Y" without a total (it reads one row more for *Next*); `max_rows` is a maximum row count (the total is counted over at most max+1 rows: "of more than N"; downloads are capped too); page numbers and sizes are clamped on the server. Cards (500), charts (1000), dynamic content (1000) and lists of values (5000) have configurable row limits. Keyset ("seek") paging on an indexed sort (`"keyset"`), with signed positions |
 | Lazy loading of regions | ✅ | `"lazy": true` on report, chart, cards, dynamic, tree and template component regions: a placeholder, fetched after the page shows (page, condition and authorization re-checked); without JavaScript a link shows the region ([chapter 4](guide/04-pages-and-regions.md#large-tables)) |
 | Region caching (per user, per session, for a duration) | ✅ | `"cache": {"scope": "user" \| "session" \| "all", "seconds": N}` keeps rendered regions in server memory, keyed by app, region, roles, language, the query string and the item values the region uses; a page submit empties it. CSRF tokens and per-user links are never shared. Per server process |
@@ -232,6 +233,7 @@ the 26.2 comparison.)
 | Automatic application backups, page groups | ✅ | (sprint 51) **Backups**: before every import that replaces an application (CLI, MCP, working copy merge, restore), daily when it changed, and by hand; the newest 25 (configurable) are kept; download and restore from the builder ([chapter 3](guide/03-builder.md#backups)); (sprint 62) Workspace utilities → **Manage backups** across the workspace's applications, with a backup of all of them at once. (sprint 58) **Page groups**: Shared Components → Page groups, a page's *Page group*, the page list by group with a filter ([chapter 3](guide/03-builder.md#page-groups)) |
 | Application availability (Available, Developers only, Restricted access, Unavailable; build status *Run only*) | ✅ | (sprint 51) Available, available to developers only (a builder session in the same browser), restricted to named users, or unavailable with a message, for pages, file downloads, REST modules and PostgREST; build status **Run only** refuses builder changes as if the application were locked, while `pgkiln import --replace` still deploys. Installation settings: not exported, kept by an import ([chapter 3](guide/03-builder.md#availability-and-build-status)) |
 | Monitoring (top SQL) | ✅ | Activity per app; Top SQL per app's database role from `pg_stat_statements` (sortable, resettable) |
+| OpenTelemetry (Workspace Utilities → OpenTelemetry, 24.2: client logging and token relay to an OTLP collector) | ✅ | (sprint 139, AP-6) Workspace utilities → **OpenTelemetry** ([chapter 1](guide/01-installation.md#monitoring-with-opentelemetry)) or the standard `OTEL_*` variables: OTLP/HTTP to any Collector. A trace per request with a span per SQL statement, REST data source and web call (W3C `traceparent` passed on), AI request (tokens) and tool call; mail and workflow steps as traces of their own; head sampling that keeps every failed trace; values (SQL literals, binds, query strings) only when chosen, the user hashed. Logs of errors, refused access and failed sign-ins; metrics of request durations, errors, AI tokens and the queues; `GET /metrics` for Prometheus. Browser spans of the page load and Ajax calls relayed by pgkiln (APEX's token relay: no collector token reaches the browser). Per workspace: off, or also its own collector through its network access list. Beyond APEX: SQL spans and Prometheus |
 | Workspace export and import (Workspace Utilities → Export) | ✅ | (sprint 67) Workspace utilities → **Export and import** (administrators and the workspace's administrators): settings (message, banner, preferences), developers and workspace administrators, application groups, extension links, REST source catalogs, SQL scripts, blueprints and data generators as one file; imported into the current workspace in one transaction, keeping or replacing components with the same name and never deleting ([chapter 3](guide/03-builder.md#export-and-import)). Applications are exported on their own; isolation, database roles and passwords never leave the installation |
 | Workspaces (multi-tenant) | ✅ | Workspaces group applications and developers: the builder shows and opens only the applications of a developer's workspaces (administrators: all), a current workspace with a switcher, new and imported applications go into it, administrators add workspaces, choose their developers and move applications ([chapter 3](guide/03-builder.md#workspaces)). (sprint 60) **Isolated workspaces** are a tenant boundary: the applications run on a PostgreSQL login of the workspace's own and its developers' SQL Workshop on another, with row-level security on pgkiln's tables, so SQL that resets its role can't reach other workspaces' applications, data, sessions or accounts; **workspace database roles** (APEX: workspace schemas) assigned by administrators; **workspace administrators** who manage their workspace's developers; SQL scripts, blueprints and sample data per workspace ([isolated workspaces](guide/03-builder.md#isolated-workspaces)). **Missing:** user directories per workspace (accounts are installation-wide, visible to the workspaces whose applications they use), developers created by a workspace administrator |
 | Mail queue reporting: delivery health, performance, failures and usage per workspace (26.2) | ✅ | (sprint 118, WS-9) Administration → **Mail queue** ([chapter 3](guide/03-builder.md#mail-queue)): queued, sent, failed and retrying mail per hour and per workspace / application, the share delivered, the average and the 10 slowest provider calls, and every failure with the provider's answer (an SMTP reply such as `550 5.1.1`), with **Retry** and **Purge** (one or all failed). Administrators see every workspace, a workspace's administrators their own |

package/docs/guide/01-installation.md

@@ -197,6 +197,15 @@ which is read at startup; real environment variables take precedence.
 | `LOG_LEVEL` | `info` | `fatal`, `error`, `warn`, `info`, `debug`, `trace` |
 | `PGKILN_RELEASE_CHECK` | `off` | `on`: the server asks GitHub once a day for a newer pgkiln release and the [Workspace home](03-builder.md#the-release-check) announces it. Administrators can also set it in the builder (Instance settings → *New versions*), which wins over the variable. Keep it off where the server may not reach the internet |
 | `PGKILN_RELEASE_URL` | GitHub's releases API | For tests and mirrors only: the address of a JSON document like GitHub's `releases/latest` |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | *(none)* | (0.72) The OpenTelemetry Collector's OTLP/HTTP address (e.g. `http://otel-collector:4318`): pgkiln sends [traces, logs and metrics](#monitoring-with-opentelemetry) there. Workspace utilities → **OpenTelemetry** wins over it and over the other `OTEL_*` variables below |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `…_LOGS_ENDPOINT`, `…_METRICS_ENDPOINT` | the endpoint + `/v1/traces` … | A full URL per signal (only when the builder sets no collector URL) |
+| `OTEL_EXPORTER_OTLP_HEADERS` | *(none)* | Headers sent to the collector, `name=value,name2=value2` (an API key) |
+| `OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES` | `pgkiln`, *(none)* | The `service.name` and other resource attributes (`deployment.environment=prod`) |
+| `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` | always on | `traceidratio` with a ratio from 0 to 1 sends that share of traces; a trace with an error is always sent |
+| `OTEL_TRACES_EXPORTER`, `OTEL_LOGS_EXPORTER`, `OTEL_METRICS_EXPORTER` | `otlp` | `none` leaves that signal out |
+| `OTEL_METRIC_EXPORT_INTERVAL` | `60000` | Milliseconds between metric exports (5 s to 1 h) |
+| `OTEL_SDK_DISABLED` | `false` | `true` turns the instance's export off, whatever the builder says |
+| `PGKILN_METRICS`, `PGKILN_METRICS_TOKEN` | `off`, *(none)* | `on` opens `GET /metrics` (Prometheus) for administrators and for scrapers that send `Authorization: Bearer <PGKILN_METRICS_TOKEN>` |
 
 ## npm scripts
 
@@ -355,6 +364,105 @@ run several instances behind a load balancer. Each instance opens up to
 `2 × (DB_POOL_SIZE + DB_NESTED_POOL_SIZE)` database connections (30 with the defaults); keep the sum
 of all instances below PostgreSQL's `max_connections` (100 by default).
 
+## Monitoring with OpenTelemetry
+
+(0.72; APEX: Workspace Utilities → OpenTelemetry) pgkiln sends **traces, logs and metrics** to your own monitoring
+over OTLP, the OpenTelemetry protocol: Grafana (Tempo, Loki, Mimir), Jaeger, Datadog, Honeycomb, New Relic, Elastic,
+OCI APM and the rest, normally through an [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/). It sends
+OTLP over HTTP as JSON (`http/json`), which every Collector accepts on port 4318. No agent and no extra package are
+needed, and nothing runs while no collector is set.
+
+Administrators set it up in Workspace utilities → **OpenTelemetry** (`/builder/telemetry`), or with the standard
+`OTEL_*` variables of the [configuration reference](#configuration-reference) (a value set in the builder wins):
+
+- **Collector URL**: the OTLP/HTTP base address; `/v1/traces`, `/v1/logs` and `/v1/metrics` are added.
+  **Headers** (an API key) are stored encrypted with `PGKILN_SECRET_KEY` (rotated by `pgkiln admin rotate-key`)
+  and never shown again, only their names. **Send a test span** sends one span and shows what the collector answered;
+  *Status* shows what each server process sent, dropped, and the last problem.
+- **What is traced.** Every application request is a trace: a server span `GET /a/:alias/:page` with the application,
+  page, HTTP status, route and the user (see below), and a child span for **each SQL statement** (`db.query.text`,
+  rows, SQLSTATE on errors; transaction control left out), **each outgoing web call** (REST data sources, `invoke_api`,
+  `meta.web_request`, web credential token requests: `HTTP GET` with the host, path and status; a 4xx/5xx answer is
+  an error span), **each AI request** (`gen_ai.*`: provider, model, input and output tokens) and **each AI tool call**
+  of an assistant or agent. A W3C `traceparent` header goes along with every outgoing web call, so the called service
+  joins the same trace, and an incoming `traceparent` (from a proxy or another service) is continued. Background work
+  has traces of its own: each **mail** sending attempt and each **workflow step** (with the `invoke_api` call inside it).
+  *Trace builder requests too* adds `/builder` requests (to the instance's collector only).
+- **Sample ratio**: the share of traces sent (0 to 1). pgkiln keeps a trace's spans until it ends, so a trace with an
+  error (an HTTP 5xx, a failing statement, a REST call answered with 500) is **always** sent.
+- **Values stay out** unless *Include values* is on: SQL statements are sent with their literals replaced by `?`
+  (`where ename = ?`), bind values, the query string, the full URL of outgoing calls and AI tool arguments are left
+  out, and quoted values, `Key (col)=(value)`, e-mail addresses and long numbers are removed from error messages.
+  With *Include values*, statements go as run, with `db.query.parameter.N`.
+- **User**: *Hashed* (the default) sends `enduser.id` as a keyed hash (the same user always gives the same value,
+  the name is not sent), *User name* sends the name, *Not sent* leaves it out.
+- **Logs**: errors (also unhandled server errors), refused access and failed or locked sign-ins, as log records tied
+  to the request's trace, with the application and page.
+- **Metrics**, every 60 seconds (`OTEL_METRIC_EXPORT_INTERVAL`): `pgkiln.http.server.duration` (a histogram in
+  milliseconds per application, method and status class), `pgkiln.errors`, `pgkiln.access_denied`,
+  `pgkiln.signin_failures`, `pgkiln.ai.requests`, `pgkiln.ai.tokens` (per provider, model, input/output),
+  `pgkiln.mail.sent`, and the levels `pgkiln.mail.queue`, `pgkiln.jobs.queue`, `pgkiln.workflows`,
+  `pgkiln.ai.requests.pending`, `pgkiln.embeddings.queue`, `pgkiln.db.pool.connections`, `process.memory.rss`,
+  `process.uptime`; `pgkiln.telemetry.dropped` counts what could not be sent.
+- **Browser spans** (optional): a page whose trace is sent carries a signed `<meta name="pgkiln-trace">`, and `app.js`
+  reports the page's load timings and its Ajax calls to `POST /a/<alias>/telemetry`; pgkiln adds them to the page's
+  trace (*browser page load*, *browser POST*). The browser never sees the collector or its headers, and the token is
+  bound to the trace, the application and 30 minutes.
+- **Prometheus**: *Prometheus endpoint /metrics* (or `PGKILN_METRICS=on`) answers `GET /metrics` in the Prometheus
+  text format, for administrators signed in to the builder and for scrapers with the metrics token (*Make a token*,
+  shown once; or `PGKILN_METRICS_TOKEN`). It works without a collector.
+
+Each **workspace** chooses on its page → *Mail and network access* → **OpenTelemetry**
+(`/builder/workspaces/<id>/telemetry`, its administrators): *As the instance does* (the default), *Nothing* (its
+applications send nothing, not even to the instance's collector), or *Also to our own collector*: an OTLP/HTTP URL
+with its own headers and its own *Include values*, reached like any outgoing call of the workspace, through the
+installation's allow-list (`PGKILN_REST_ALLOWED_HOSTS`) and the workspace's [network access](03-builder.md#network-access)
+list. Its resource carries `pgkiln.workspace.id`. Metrics go to the instance's collector only.
+
+A Collector that sends traces to Jaeger, for a first look (`docker compose`):
+
+```yaml
+services:
+  jaeger:
+    image: jaegertracing/all-in-one:1.62.0     # the UI on http://localhost:16686
+    environment: { COLLECTOR_OTLP_ENABLED: "true" }
+  otel-collector:
+    image: otel/opentelemetry-collector-contrib:0.114.0
+    command: ["--config=/etc/otel.yaml"]
+    volumes: ["./otel.yaml:/etc/otel.yaml:ro"]
+    ports: ["4318:4318"]
+```
+
+```yaml
+# otel.yaml
+receivers:
+  otlp: { protocols: { http: { endpoint: 0.0.0.0:4318 } } }
+exporters:
+  otlp/jaeger: { endpoint: jaeger:4317, tls: { insecure: true } }
+  debug: {}
+service:
+  pipelines:
+    traces: { receivers: [otlp], exporters: [otlp/jaeger] }
+    logs: { receivers: [otlp], exporters: [debug] }
+    metrics: { receivers: [otlp], exporters: [debug] }
+```
+
+Set `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318` (or the URL in the builder), open a page, and its trace shows
+in Jaeger under the service `pgkiln`. A Prometheus scrape job for `/metrics`:
+
+```yaml
+scrape_configs:
+  - job_name: pgkiln
+    metrics_path: /metrics
+    authorization: { credentials: "<the metrics token>" }
+    static_configs: [{ targets: ["apps.example.com:443"] }]
+    scheme: https
+```
+
+Every server process sends what it saw: with several instances, each is a `service.instance.id` (host and process).
+A collector that is down costs a failed request per batch every few seconds, never a user's request; what doesn't fit
+the queue (8,192 spans per collector) is dropped and counted.
+
 ## Backups and moving applications
 
 - **Everything** is in PostgreSQL: application definitions (`meta.*`), sessions and your data.