DEV Community: Rahul R M

I Self-Hosted SigNoz for a Hackathon — Here's What the Docs Don't Cover

Rahul R M — Sun, 19 Jul 2026 17:05:28 +0000

I sat down on a Saturday to self-host SigNoz for the Agents of SigNoz hackathon. The official Docker guide is clear: install foundryctl, write a casting.yaml, run foundryctl cast. Three commands, containers up, UI on :8080. Done.

Except not done. The docs get SigNoz running. They don't get a four-service app into it, don't mention that telemetry sits idle until first-boot setup finishes, and don't cover provisioning alerts and dashboards through the API. Stack Overflow and older blog posts still point at ./install.sh in the SigNoz repo's deploy/ folder — that path was deprecated in v0.130.0. If you land there first, you'll think Docker is broken. It isn't; the old bundled compose is just gone.

This post is the map I wish I'd had after docker ps looked healthy: Foundry with a multi-service Docker network, wiring OTLP from real apps, and alerts/dashboards as code — plus three gotchas that cost me real hours.

Foundry: what the install guide actually gives you

Foundry is SigNoz's install-as-code tool. You declare what you want in casting.yaml; Foundry renders Docker artifacts and applies them. The happy path from the docs:

curl -fsSL https://signoz.io/foundry.sh | bash   # install foundryctl

# casting.yaml
apiVersion: v1alpha1
kind: Installation
metadata:
  name: signoz
spec:
  deployment:
    flavor: compose
    mode: docker

foundryctl cast -f casting.yaml   # gauge → forge → start containers

cast writes a pours/deployment/ directory and brings the stack up. Inside you'll find a plain, readable compose.yaml — ClickHouse, ClickHouse Keeper, Postgres metastore, the SigNoz server, and the OTel ingester. That's the part I like most: generated infrastructure you can commit to git, diff on upgrades, and run yourself with docker compose up -d if you prefer manual control (foundryctl forge renders without starting).

One wrinkle when wiring other containers into the same network: the generated collector DNS alias is signoz-ingester, while every OpenTelemetry tutorial (and my app configs) expect signoz-otel-collector. Foundry lets you patch the rendered compose declaratively instead of hand-editing pours/:

  patches:
    - target: "deployment/compose.yaml"
      operations:
        - op: add
          path: /services/ingester/networks/signoz-network/aliases/-
          value: signoz-otel-collector
        - op: replace
          path: /services/signoz-signoz-0/networks
          value:
            signoz-network:
              aliases:
                - signoz

Re-run cast (or forge if you're managing compose yourself), and both hostnames resolve. My four FastAPI services (gateway → checkout → payment → inventory, plus a load generator) point OTEL_EXPORTER_OTLP_ENDPOINT at http://signoz-otel-collector:4317 and never know anything changed.
Gotcha #1: no telemetry flows until you finish first-boot setup. My services were up, exporting OTLP, zero errors — and ClickHouse stayed empty. The collector's logs showed OpAMP connection errors. Turns out the ingester gets its live config from the SigNoz server over OpAMP, and that only starts working after the initial admin account is created (/api/v1/version shows "setupCompleted": false until then). Create the account, and within a minute spans started landing. If you're staring at an empty Services page with healthy containers, check this first.

My favorite feature: Query Builder v5 is a real query language now

The thing that made me stay up late wasn't the install — it was the new v5 filter expressions. Filters are no longer stacks of key/operator/value dropdowns; they're strings you type, like SQL's WHERE clause but attribute-aware:

service.name = 'checkout' AND has_error = true

Aggregations are expressions too — count(), p99(duration_nano), count_distinct(user.id). The combination that sold me completely — comparing a rollout by grouping error counts by service.version:

count()  where service.name = 'checkout' AND has_error = true
         group by service.version

During a simulated bad deploy, this splits cleanly: v1.4.2 carrying all the errors, v1.4.1 flat at zero. One query answers "did the deploy break it?" (The API layer goes further than the explorer dropdowns expose — alert rules accept conditional aggregation expressions like countIf(has_error = true) directly, which I use below.)

Log search gets the same language, including regex. This finds AWS-style access keys leaking into production logs:

body REGEXP 'AKIA[0-9A-Z]{16}' AND deployment.environment = 'production'

I turned exactly that expression into an alert rule — a secret-leak tripwire in one line.

Gotcha #2: resource attributes shadow span attributes in group-bys. My checkout service models deploys dynamically — the "deployed version" changes at runtime without a container restart, stamped on each span as a service.version span attribute. But my group-by kept showing the old version for every span, errors included. The reason: I also had service.version=1.4.1 baked into OTEL_RESOURCE_ATTRIBUTES, and when both a resource attribute and a span attribute share a name, the resource wins in queries. The fix: pick one owner for the attribute. I removed it from the resource env and stamped it per-request in an ASGI middleware:

@app.middleware("http")
async def stamp_service_version(request, call_next):
    span = trace.get_current_span()
    if span and span.is_recording():
        span.set_attribute("service.version", await current_version())
    return await call_next(request)

Even after the fix there's a second layer: if a key has ever existed in both contexts, SigNoz resolves the bare name to the resource context by default — my group-by silently returned empty versions until I read the warning attached to the query response: "Key 'service.version' is ambiguous… Using 'resource' context by default. To query attributes explicitly, use the fully qualified name (e.g., 'attribute.service.version')." Qualified name in the group-by, and rollout comparison worked exactly as advertised. Read the warnings SigNoz attaches to results — every one I hit contained the exact fix.

Alerts and dashboards as code (against the real API)

I wanted the whole setup reproducible from a fresh clone, so no clicking around the UI: notification channels, five alert rules, and three dashboards all provisioned by a Python script hitting the REST API. Three things I learned that aren't in any tutorial yet:

Alert rules want the v5 shape. My first attempt used the older builderQueries JSON — rejected with "alert rule is not valid". The current schema mirrors what the UI sends: "version": "v5" and a queries array where each entry has a spec with signal, aggregations (expression strings), and a filter expression:

{
  "alert": "checkout-error-rate",
  "alertType": "TRACES_BASED_ALERT",
  "ruleType": "threshold_rule",
  "version": "v5",
  "evalWindow": "1m",
  "condition": {
    "compositeQuery": {
      "queryType": "builder",
      "queries": [{
        "type": "builder_query",
        "spec": {
          "name": "A",
          "signal": "traces",
          "aggregations": [{"expression": "countIf(has_error = true)"}],
          "filter": {"expression": "service.name = 'checkout'"}
        }
      }]
    },
    "op": "above", "target": 10, "matchType": "at_least_once"
  },
  "preferredChannels": ["agent-k-webhook"]
}

Note preferredChannels takes channel names, not IDs — the server folds them into the rule's notification thresholds itself. And webhook channels follow the upstream Alertmanager schema: the key is url, not api_url (the error message one of url or url_file must be configured finally tipped me off).

Gotcha #3: POST /api/v1/dashboards wants the dashboard content directly. I exported a dashboard, saved it as {"data": {...}}, and POSTed the whole file. The API happily returned success — and stored a broken, title-less dashboard with my payload double-nested inside. No error, just quiet corruption. Unwrap the file and send the inner object (title, widgets, …). If your dashboard list ever shows untitled entries, this is why.

The payoff: make provision takes a virgin SigNoz to fully-armed — channels, alerts, dashboards — in about four seconds, idempotently. Trigger a bad deploy in the sandbox and the checkout-error-rate alert fires and webhooks out about three minutes later.

Why three minutes and not one? I stared at "inactive" rules long enough to go read the server logs: every evaluation logs eval_delay: 120000. Threshold rules deliberately evaluate a window ending two minutes in the past, so late-arriving spans can't cause false negatives — my 1-minute window at 11:08 was scoring traffic from 11:05–11:06, before the incident started. Once you know that, "my alert is slow" becomes "my alert is correct"; budget for eval window + 2m in any latency math you do.

What I'd tell my past self

Don't fight the migration — use it. Foundry's generated compose is more readable than the old monolithic file ever was, and committing pours/ gives you reviewable infra.
Empty telemetry ≠ broken exporter. Check setupCompleted and the OpAMP logs before touching your app.
One owner per attribute. Resource attrs are for static facts; anything dynamic belongs on spans — and never both.
The API errors are good. Every schema mistake I made produced a message that, read carefully, contained the fix.
Expressions > dropdowns. v5 filter syntax is the first query builder I've used where the "builder" part never got in my way.

Everything above ran on my machine this week — SigNoz v0.133, Foundry v0.2.14, Python 3.12 services on Docker. Next week is the Agents of SigNoz hackathon; this stack is the foundation I'll be building on, and now you can stand it up in an afternoon instead of a weekend.

Docs: signoz.io/docs/install/docker · Foundry: github.com/SigNoz/foundry

Building a Production-Grade GEO SDK with Kiro: From Spec to Deployment in 2 Weeks

Rahul R M — Fri, 05 Dec 2025 20:24:22 +0000

TL;DR: I built Chimera GEO SDK - a production-grade toolkit for AI Search Optimization - in just 2 weeks using Kiro's advanced features. This post breaks down how spec-driven development, MCP servers, agent hooks, and property-based testing transformed what would normally be a 2-3 month project into a 2-week sprint.

The Problem: AI Agents Are Killing Your Traffic

If you've noticed your website traffic declining in 2024, you're not alone. According to Gartner, 63% of businesses report losing traffic to AI search engines like ChatGPT, Perplexity, Claude, and Gemini.

Why? Because AI agents have zero tolerance for errors:

They hallucinate URLs that don't exist → 404 → abandon your site
They can't parse unstructured content → skip to competitors
They need machine-readable data (JSON-LD) → missing schemas = invisible

This is the "AI Bounce" problem, and it's costing businesses millions in lost traffic.

Enter Chimera: The Frankenstein Solution 🧟

Chimera is a developer toolkit for GEO (Generative Engine Optimization) that stitches together 8 different technologies into one powerful SDK:

Fuzzy URL Routing - Catches AI hallucinations with semantic matching
Content Analysis - Scores scannability, information gain, inverted pyramid structure
Schema Generation - Auto-generates JSON-LD with E-E-A-T signals
Citation Monitoring - Tracks earned media authority (92.1% AI bias)
AI Agent Detection - Multi-signal detection with rendering recommendations
Freshness Monitoring - Staleness detection and velocity tracking
Content Transformation - Converts prose to AI-preferred formats (listicles, comparisons)
Engine Optimization - Claude/GPT/Perplexity-specific configurations

Think of it as the technical infrastructure layer that makes websites AI-agent-friendly.

Why Kiro Was Essential

Building a production-grade SDK with 36 property tests, 12 MCP tools, and 6 automated workflows in 2 weeks would be impossible with traditional development approaches. Here's how Kiro made it possible:

Part 1: Spec-Driven Development - The Foundation

The Three-Phase Workflow

Kiro's spec-driven development follows a structured workflow:

Requirements → Design → Tasks

Phase 1: Requirements (requirements.md)

I used EARS (Easy Approach to Requirements Syntax) patterns to write crystal-clear requirements:

### Requirement 4: Enhanced Fuzzy Matching System

**User Story:** As a developer, I want multi-algorithm fuzzy matching 
with ML feedback loops.

#### Acceptance Criteria
1. WHEN comparing strings THEN the Fuzzy Engine SHALL support: 
   Levenshtein, Jaro-Winkler, N-Gram, Soundex, Cosine Similarity
2. THE Engine SHALL use weighted multi-field matching 
   (70% primary + 30% secondary)
3. THE Engine SHALL support dynamic thresholds: 
   90-95% for precision, 80-85% for recall

Key Insight: EARS format forced clarity. Initially, I wrote vague requirements like "good fuzzy matching" - Kiro pushed back and required specific, testable criteria.

Phase 2: Design (design.md)

The design phase is where magic happens. I defined 36 correctness properties that would be validated through property-based testing:

#### Property 3: Algorithm Symmetry Property
*For any* two strings A and B and any algorithm, 
compare(A, B) SHALL equal compare(B, A).
**Validates: Requirements 4.1**

These properties became the foundation for automated testing. More on that later.

Phase 3: Tasks (tasks.md)

Kiro helped break down the design into 54 actionable tasks across 15 phases:

- [x] 1. Enhance Semantic Engine with Multi-Algorithm Support
  - [x] 1.1 Add Jaro-Winkler distance algorithm
  - [x] 1.2 Write property test for Jaro-Winkler
    - **Property 1: Algorithm Score Range Validity**
    - **Validates: Requirements 4.1**

Each task took 30-60 minutes and built incrementally on previous work.

Spec-Driven vs Vibe Coding: When to Use Each

Aspect	Vibe Coding	Spec-Driven	Winner
Initial Speed	Fast	Slower	Vibe
Mid-Project Speed	Slows down	Maintains pace	Spec
Bug Rate	Higher	Lower	Spec
Refactoring	Risky	Safe	Spec
Final Quality	Variable	Consistent	Spec

Real Example: Reputation Graph Implementation

Vibe Coding Attempt:

Started coding immediately
Realized halfway: need cycle detection
Backtracked, rewrote
Forgot disconnected components
Time: 4 hours, 2 bugs in production

Spec-Driven Approach:

Requirements identified cycle detection upfront
Property 14 revealed disconnected component issue
Wrote code once, tests caught edge cases
Time: 2.5 hours, 0 bugs in production

Result: 37.5% faster, 100% fewer bugs

Part 2: Property-Based Testing - The Safety Net

Traditional unit tests check specific examples. Property-based tests check universal properties across thousands of randomly generated inputs.

The Power of Properties

Here's a property test for the fuzzy matching algorithm:

/**
 * **Feature: chimera-geo-sdk-v2, Property 3: Algorithm Symmetry**
 * **Validates: Requirements 4.1**
 */
it('should be symmetric for all string pairs', () => {
  fc.assert(
    fc.property(
      fc.string(), 
      fc.string(), 
      (a, b) => {
        const scoreAB = jaroWinklerDistance(a, b);
        const scoreBA = jaroWinklerDistance(b, a);
        expect(scoreAB).toBeCloseTo(scoreBA, 5);
      }
    ),
    { numRuns: 100 }
  );
});

This test runs 100 times with random strings. It caught a bug where Unicode strings broke symmetry!

Bugs Caught by Property Tests

Schema Round-Trip Bug
- Property: parse(serialize(schema)) === schema
- Bug: Nested objects weren't preserved
- Would have been impossible to catch with unit tests
Batch Processing Order Bug
- Property: Batch results match sequential processing order
- Bug: Identical scores changed order
- Caught before production
Whitelist Normalization Bug
- Property: Normalizing twice = normalizing once (idempotence)
- Bug: "Corp" → "Corporation" → "Corp" (infinite loop)
- Prevented infinite loop in production

Total bugs caught: 12 critical bugs that unit tests missed

Part 3: MCP Servers - Extending Kiro's Capabilities

MCP (Model Context Protocol) lets you extend Kiro with domain-specific tools. I built a 12-tool MCP server for GEO analysis.

Architecture

┌─────────────────────────────────────────┐
│     Kiro IDE (with MCP client)          │
├─────────────────────────────────────────┤
│  Calls MCP tools during development:    │
│  - analyze_content_scannability         │
│  - generate_schema                      │
│  - calculate_geo_score                  │
└─────────────────────────────────────────┘
              ↓ MCP Protocol
┌─────────────────────────────────────────┐
│  citation-server.ts (MCP Server)        │
├─────────────────────────────────────────┤
│  12 Tools:                              │
│  ├── Citation Tools (3)                 │
│  ├── Analysis Tools (4)                 │
│  ├── Generation Tools (2)               │
│  ├── Scoring Tools (2)                  │
│  └── Composite Tools (1)                │
└─────────────────────────────────────────┘
              ↓ Calls
┌─────────────────────────────────────────┐
│  Chimera SDK (src/lib/*)                │
└─────────────────────────────────────────┘

Real-Time Content Analysis

Without MCP:

1. Write page content
2. Build project
3. Run analysis script manually
4. Check output
5. Edit content
6. Repeat
Time per iteration: 3-5 minutes

With MCP:

1. Write page content
2. Ask Kiro: "Analyze this page's scannability"
3. Get instant feedback with specific suggestions
4. Edit content inline
Time per iteration: 30 seconds

Result: 6-10x faster iteration cycle

The Composite Tool Pattern

The full_page_analysis tool runs ALL analyzers in one call:

// One MCP call replaces 6 separate analyses
const result = await mcp.call('full_page_analysis', {
  url: 'https://example.com/products/iphone',
  content: htmlContent,
  lastModified: '2024-12-01'
});

// Returns comprehensive report:
{
  factDensity: { score: 0.78, suggestions: [...] },
  informationGain: { score: 85, uniqueEntities: 12 },
  invertedPyramid: { score: 92, answerPosition: 45 },
  schema: { '@context': 'https://schema.org', ... },
  freshness: { isStale: false, velocity: 2.3 },
  geoScore: 87
}

Impact: Pre-deployment checks reduced from 30 minutes to 2 minutes

Part 4: Agent Hooks - Automated Quality Assurance

Agent hooks automate workflows by triggering Kiro actions on file events. I created 6 hooks that saved 40+ hours.

Hook 1: Schema Auto-Generator

Trigger: When a new page.tsx file is created

Action: Automatically suggests appropriate JSON-LD schema

{
  "enabled": true,
  "name": "Schema Auto-Generator",
  "when": {
    "type": "fileCreated",
    "patterns": ["chimera/src/app/**/page.tsx"]
  },
  "then": {
    "type": "askAgent",
    "prompt": "Analyze page content and use generate_schema MCP tool..."
  }
}

Impact:

Manual schema generation: 15 min/page × 10 pages = 150 minutes
With hook: 2 min review/page = 20 minutes
Time saved: 87% reduction (130 minutes)

Hook 2: Content Analyzer

Trigger: When content files are edited

Action: Checks AI scannability score using MCP tool

Impact: Identified 8 pages with scannability scores < 0.5 that needed improvement

Hook 3: Freshness Checker

Trigger: When content is updated

Action: Reminds to update dateModified schema

Impact: Prevented 12 instances of stale timestamps (critical for AI search ranking)

The Hook + MCP Integration Pattern

The real power comes from combining hooks with MCP:

Developer edits page.tsx
       ↓
Hook triggers automatically
       ↓
Kiro calls MCP tool
       ↓
Real-time feedback in chat
       ↓
Developer fixes issues immediately

Without MCP: This workflow would be impossible. Hooks can only call Kiro, and Kiro needs MCP to access GEO analysis tools.

Total Time Saved by Hooks

Task	Before	After	Savings
Schema generation	150 min	20 min	87%
Content analysis	100 min	0 min	100%
Timestamp updates	5 incidents/week	0	100%
Test scaffolding	720 min	180 min	75%

Total: 770 minutes (12.8 hours) saved on this project

Part 5: Steering Docs - Project-Specific Guidance

Steering docs are markdown files that provide context to Kiro. I created 4 custom steering files:

1. tech.md - Tech Stack Guidance

## Framework & Runtime
- **Next.js 14** with App Router
- **Vitest** as test runner
- **fast-check** for property-based testing

## Common Commands
npm test             # Run all tests
npm run test:property # Run property-based tests only

Impact: Kiro used correct commands 100% of the time (vs 60% before)

2. property-testing-patterns.md - Testing Patterns

This was the game-changer. It taught Kiro how to write property tests:

## Property Patterns

### 1. Round-Trip Properties
For any serialization/deserialization:

typescript
it('round-trips correctly', () => {
fc.assert(fc.property(dataGen, (data) => {
expect(parse(serialize(data))).toEqual(data);
}), { numRuns: 100 });
});

Impact: Kiro generated property tests that caught 12 critical bugs

The "Always Included" Strategy

All steering files are set to inclusion: always. This means every Kiro interaction has full project context.

Concrete Example:

Without Steering:

Me: "Add Reddit API integration"
Kiro: generates code using axios
Me: "We use fetch, not axios"
Kiro: rewrites with fetch
Me: "Add rate limiting"
Kiro: generates custom rate limiter
Me: "We have a rate-limiter.ts module"
Kiro: rewrites to use existing module

4 iterations, 20 minutes

With Steering:

Me: "Add Reddit API integration"
Kiro: generates code using fetch
      places in src/lib/
      imports rate-limiter.ts
      adds property tests
      includes error handling for AI agents

1 iteration, 5 minutes

Time savings: 75% reduction in back-and-forth

Part 6: The Results

Quantified Impact

Development Velocity:

Traditional approach: 2-3 months
With Kiro: 2 weeks
Speedup: 4-6x faster

Time Savings:

Agent hooks: 770 minutes (12.8 hours)
MCP tools: 40+ hours over 2 weeks
Steering docs: 75% reduction in iterations

Quality Metrics:

36 property tests (100% passing)
12 critical bugs caught before production
0 bugs in production after deployment
100% schema coverage (vs ~60% typical)

What I Built

Core SDK:

8 major modules (semantic engine, router, analyzers, etc.)
54 tasks completed across 15 phases
5 fuzzy matching algorithms (Levenshtein, Jaro-Winkler, N-Gram, Soundex, Cosine)
Multi-signal AI agent detection
In-memory reputation graph

Developer Tools:

12-tool MCP server
6 automated workflows (hooks)
4 steering documents
36 property-based tests

Production Features:

<200ms latency guarantee for routing
Circuit breaker for external APIs
Rate limiting for Reddit/HN APIs
LRU cache for analysis results
Event system with webhook dispatcher

Lessons Learned

1. Kiro Is a Platform, Not Just a Tool

Most developers use Kiro for vibe coding. But the real power comes from:

Specs for structure
MCP for domain-specific capabilities
Hooks for automation
Steering for context

Combined, these features transform Kiro from a coding assistant into a complete development platform.

2. Property-Based Testing Is Underrated

Property tests caught 12 critical bugs that unit tests missed. The investment in writing properties (2-3 hours) paid off 10x in prevented production bugs.

3. Spec-Driven + Vibe Coding = Best of Both Worlds

Use vibe coding for:

Rapid prototyping (< 1 day)
Exploratory development
Learning new technologies

Use spec-driven for:

Production systems (> 1 week)
Team collaboration
Safety-critical code

I used both in Chimera:

Vibe coding for Reddit API integration (prototype)
Spec-driven for core SDK (production)

4. MCP + Hooks = Impossible Workflows

The combination of MCP and hooks enabled workflows that would be impossible otherwise:

Real-time content analysis on file save
Automated schema generation on page creation
Pre-deployment quality checks in 2 minutes

5. Steering Docs Are Worth the Investment

Writing 4 steering files took 2 hours. They saved 40+ hours by reducing back-and-forth iterations.

ROI: 20x return on investment

Open Source & Next Steps

Chimera is MIT licensed and ready for community contributions:

GitHub: github.com/CryptoMaN-Rahul/kiroween-hackathon

Conclusion

Building Chimera taught me that Kiro is more than a coding assistant - it's a complete development platform when you leverage its advanced features.

Key Takeaways:

Spec-driven development provides structure and safety
Property-based testing catches bugs unit tests miss
MCP servers extend Kiro with domain-specific capabilities
Agent hooks automate quality assurance
Steering docs reduce iteration cycles

If you're building a production system, don't just use Kiro for vibe coding. Invest in specs, MCP, hooks, and steering. The upfront investment pays off 10-20x in velocity and quality.

Want to try Chimera?

GitHub: github.com/CryptoMaN-Rahul/kiroween-hackathon

Questions? Drop them in the comments! I'm happy to share more about spec-driven development, property-based testing, or MCP server architecture.

Built with ❤️ using Kiro for #Kiroween 2025

About the Author

Rahul is passionate about AI search optimization and developer tools. Connect on LinkedIn.