Skip to content

[recipes] Operational monitoring and brain health#13

Open
alanshurafa wants to merge 7 commits intomainfrom
contrib/alanshurafa/brain-health-monitoring
Open

[recipes] Operational monitoring and brain health#13
alanshurafa wants to merge 7 commits intomainfrom
contrib/alanshurafa/brain-health-monitoring

Conversation

@alanshurafa
Copy link
Copy Markdown
Owner

Summary

  • 8 SQL monitoring views for operational observability of an Open Brain instance
  • Covers source volumes, enrichment gaps, type/sensitivity distribution, ingestion pipeline, entity queue, and graph coverage
  • Includes a runbook explaining what "healthy" looks like for fresh installs vs established brains

Views

View Requires Purpose
ops_source_volume_24h enhanced-thoughts Thought counts per source (24h)
ops_recent_thoughts enhanced-thoughts Latest thoughts with metadata
ops_enrichment_gaps enhanced-thoughts Unenriched thoughts backlog
ops_type_distribution enhanced-thoughts Type breakdown (all-time, 7d, 24h)
ops_sensitivity_distribution enhanced-thoughts Sensitivity tier breakdown
ops_ingestion_summary smart-ingest-tables Ingestion job status counts
ops_stalled_entity_queue knowledge-graph Stuck/failed queue items
ops_graph_coverage knowledge-graph Entity extraction progress %

Test plan

  • Verify gate checks pass
  • Run SQL in test project, verify views created
  • Query each view against a populated brain
  • Confirm views 6-8 error gracefully if optional schemas not installed

🤖 Generated with Claude Code

Eight SQL views for monitoring source volumes, enrichment gaps,
type/sensitivity distribution, ingestion pipeline status, entity
extraction queue health, and graph coverage percentage.

Views 1-5 work with base enhanced thoughts; views 6-8 require
optional smart-ingest-tables and knowledge-graph schemas. Includes
a runbook explaining what healthy looks like for fresh installs
vs established brains.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@github-actions github-actions bot added the recipe label Apr 6, 2026
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 558b327661

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +165 to +167
GRANT SELECT ON public.ops_ingestion_summary TO service_role;
GRANT SELECT ON public.ops_stalled_entity_queue TO service_role;
GRANT SELECT ON public.ops_graph_coverage TO service_role;
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Skip GRANTs when optional views are not created

The script instructs users without smart-ingest-tables/knowledge-graph to skip views 6–8, but these unconditional GRANT statements still reference those optional views. In that common setup, GRANT SELECT ON public.ops_ingestion_summary (and the next two grants) raises relation does not exist, so the run does not complete cleanly and later statements (including schema reload) may not execute depending on the SQL runner. Make these grants conditional or split optional views/grants into separate files so base installs can run the recipe without manual grant edits.

Useful? React with 👍 / 👎.

alanshurafa and others added 2 commits April 6, 2026 13:32
Add blank lines around headings (MD022), fenced code blocks (MD031),
and between adjacent blockquotes (MD028). Fix broken link fragment
(MD051) and remove extra blank line (MD012). No content changes.

These errors were blocking CI on all open PRs since the lint check
runs repo-wide.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Each section's numbered list now restarts at 1 instead of continuing
the global count (3-14), satisfying markdownlint MD029/ol-prefix rule.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@github-actions github-actions bot added documentation Improvements or additions to documentation integration labels Apr 6, 2026
alanshurafa and others added 4 commits April 6, 2026 13:53
Views depending on ingestion_jobs and entity_extraction_queue are now
wrapped in DO blocks that check for table existence before creating.
GRANTs moved inside the conditionals so they can't fail when optional
schemas aren't installed.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation integration recipe

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant