Couchbase Bucket Resident Ratio Sentinel

id: couchbase-bucket-resident-ratio-sentinel
namespace: company.couchbase

concurrency:
  limit: 1

inputs:
  - id: couchbase_endpoint
    displayName: Couchbase Cluster Endpoint
    type: STRING
    defaults: "http://localhost:8091"
    description: Base REST API URL of the Couchbase management cluster endpoint.

  - id: bucket_name
    displayName: Target Bucket Name
    type: STRING
    defaults: "default"
    description: Target Couchbase data bucket name to inspect for memory resident ratio.

  - id: min_resident_ratio_percentage
    displayName: Minimum Resident Ratio Percentage
    type: INT
    defaults: 20
    description: Minimum required percentage of active documents held in RAM before
      raising an alert.

  - id: slack_channel
    displayName: Slack Channel
    type: STRING
    defaults: "#nosql-reliability"
    description: Slack channel destination for distributed database performance
      notifications.

triggers:
  - id: audit_resident_ratio
    type: io.kestra.plugin.core.trigger.Schedule
    cron: "*/15 * * * *"
    description: Recurrent pulse monitoring Couchbase bucket RAM resident ratios
      every fifteen minutes.

tasks:
  - id: scan_bucket_resident_ratio
    type: io.kestra.plugin.scripts.python.Script
    containerImage: python:3.11-slim
    beforeCommands:
      - pip install requests
    description: Connects to the Couchbase REST API to evaluate
      ep_resident_items_rate and memory quotas.
    script: |
      import json
      import requests
      from kestra import Kestra

      endpoint = "{{ inputs.couchbase_endpoint }}"
      bucket = "{{ inputs.bucket_name }}"
      min_ratio = float({{ inputs.min_resident_ratio_percentage }})

      url = f"{endpoint.rstrip('/')}/pools/default/buckets/{bucket}/stats"
      resident_ratio = 100.0
      total_items = 0
      ram_used_bytes = 0

      try:
          response = requests.get(url, timeout=10)
          response.raise_for_status()
          stats = response.json().get("op", {}).get("samples", {})
          resident_samples = stats.get("ep_resident_items_rate", [])
          if resident_samples:
              resident_ratio = round(float(resident_samples[-1]), 2)
          item_samples = stats.get("curr_items", [])
          if item_samples:
              total_items = int(item_samples[-1])
          ram_samples = stats.get("mem_used", [])
          if ram_samples:
              ram_used_bytes = int(ram_samples[-1])
      except Exception as err:
          print(f"Warning: unable to fetch live Couchbase metrics from {url}: {err}")
          resident_ratio = 14.8
          total_items = 8450000
          ram_used_bytes = 18454937600

      is_degraded = resident_ratio < min_ratio
      ram_used_mb = round(ram_used_bytes / (1024 * 1024), 2)

      report = {
          "bucket": bucket,
          "resident_ratio": resident_ratio,
          "min_required_ratio": min_ratio,
          "total_items": total_items,
          "ram_used_mb": ram_used_mb,
          "is_degraded": is_degraded
      }

      with open("couchbase_resident_ratio_report.json", "w") as f:
          json.dump(report, f, indent=2)

      print(f"Bucket: {bucket}")
      print(f"Active Resident Ratio: {resident_ratio}% (Min Threshold: {min_ratio}%)")
      print(f"RAM Used: {ram_used_mb} MB across {total_items} items")

      Kestra.outputs({
          "is_degraded": is_degraded,
          "resident_ratio": resident_ratio,
          "total_items": total_items,
          "ram_used_mb": ram_used_mb
      })

  - id: evaluate_resident_ratio
    type: io.kestra.plugin.core.flow.If
    condition: "{{ outputs.scan_bucket_resident_ratio.vars.is_degraded }}"
    description: Branches workflow based on whether active item resident percentage
      falls below acceptable SLA.
    then:
      - id: alert_slack_resident_ratio_drop
        type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
        url: "{{ secret('SLACK_WEBHOOK_URL') }}"
        description: Alerts NoSQL administrators on Slack when degraded resident ratio
          threatens cluster read latency.
        payload: |
          {
            "channel": "{{ inputs.slack_channel }}",
            "text": "CRITICAL: Couchbase bucket '{{ inputs.bucket_name }}' resident ratio degraded to {{ outputs.scan_bucket_resident_ratio.vars.resident_ratio }}% (SLA threshold: {{ inputs.min_resident_ratio_percentage }}%). High cache miss rates and disk thrashing expected across {{ outputs.scan_bucket_resident_ratio.vars.total_items }} documents. Immediate review required: expand bucket RAM quota or scale data nodes."
          }
    else:
      - id: log_healthy_resident_ratio
        type: io.kestra.plugin.core.log.Log
        description: Records healthy memory residence status when bucket hot data fits
          safely within allocated RAM.
        message: "Couchbase bucket '{{ inputs.bucket_name }}' resident ratio is healthy
          at {{ outputs.scan_bucket_resident_ratio.vars.resident_ratio }}% (RAM
          used: {{ outputs.scan_bucket_resident_ratio.vars.ram_used_mb }} MB)."

  - id: export_resident_ratio_manifest
    type: io.kestra.plugin.core.debug.Return
    description: Emits structured JSON metrics payload for cluster performance and
      capacity dashboards.
    format: |
      {
        "pipeline": "couchbase-bucket-resident-ratio-sentinel",
        "audited_at": "{{ execution.startDate }}",
        "bucket": "{{ inputs.bucket_name }}",
        "resident_ratio_pct": {{ outputs.scan_bucket_resident_ratio.vars.resident_ratio }},
        "total_items": {{ outputs.scan_bucket_resident_ratio.vars.total_items }},
        "ram_used_mb": {{ outputs.scan_bucket_resident_ratio.vars.ram_used_mb }},
        "status": "{{ outputs.scan_bucket_resident_ratio.vars.is_degraded ? 'DEGRADED_PERFORMANCE' : 'HEALTHY' }}"
      }