====== BTP Cloud Foundry Application Stats Monitor ======
The BTP Cloud Foundry Application Stats Monitor provides comprehensive monitoring of Cloud Foundry applications deployed on SAP BTP. It tracks application health, resource usage, and instance status in real-time by communicating directly with the Cloud Foundry V3 API.

===== Prerequisites =====

Network connectivity from the collector to BTP API endpoints (e.g., ''api.cf.eu10.hana.ondemand.com'').

**BTP Credentials**: A user with at least Space Auditor permissions for the target spaces.

**Endpoints accessed**:
''/v3/apps'': To discover applications and their relationships (Space/Org).
''/v3/apps/{guid}/processes/web/stats'': To retrieve real-time resource usage and instance states.
Authentication: OAuth2 Password Grant (handled automatically using the configured User Profile).

===== API Endpoints used ===== 

^ Endpoint ^ Purpose ^ 
| POST /oauth/token | Authentication (via UAA login endpoint) | 
| GET /v3/apps | Discovery of all apps with Org/Space details | 
| GET /v3/apps/{guid}/processes/web/stats | Retrieve instance-level statistics |

===== Key Features =====

==== Metrics Collection ====
The monitor collects the following metrics for each application instance:
Running Instances - Count of instances in ''RUNNING'' state.
Crashed Instances - Count of instances in ''CRASHED'' or ''DOWN'' state.
Memory Usage - Current consumption (MB) and quota utilization (%).
Disk Usage - Current consumption (MB) and quota utilization (%).
CPU Usage - CPU utilization percentage (0-100%).

==== Alarm Capabilities ====
  * State Monitoring - Detect when instances enter undesired states (''CRASHED'', ''DOWN'', ''FAILED'', ''UNKNOWN''). NOT_RUNNING includes all the failed states.
  * Resource Thresholds - Multi-level thresholds (Warning, Critical, etc.) for Memory, Disk, and CPU usage using the standard ''G2W:80 W2M:90'' format - [[products:promonitor:latest:monitorsguide:commonsettings| Multi thresholds syntax]]
  * Auto-Clear - Automatically resolves alarms when the application returns to a healthy state.


==== Advanced Discovery ====
Wildcard Support: Use ''*'' in the App Name field to monitor all apps matching optional Subaccount/Space filters.
Discover All Mode: An optional toggle to collect metrics for //every// application in the subaccount, even if not explicitly listed in the configuration table (metrics only, no alarms).
Parallel Execution: Uses a thread pool to fetch statistics for multiple applications simultaneously, significantly reducing collection time.

===== How It Works =====

==== Data Collection Process ====

Authentication: Converts the API URL to a Login URL (''api.cf...'' → ''login.cf...'') to fetch an OAuth2 token, which is then cached.
Metadata Caching: Discovered applications (Names, GUIDs, Orgs, Spaces) are cached for 1 hour to minimize API overhead.
Process Stats: For each app, the monitor specifically targets the ''web'' process statistics.
State Evaluation: Alarms are raised per-app for state issues and per-instance for resource usage.

===== Configuration =====

==== Connection Settings ====

Create a Web Service Connector:
URL: Your BTP API endpoint (e.g., ''https://api.cf.eu10.hana.ondemand.com'').
Auth Type: Ensure the connector is associated with a User Profile containing valid BTP credentials.
==== Monitor Configuration ====
=== Method 1: Load BTP Apps (Recommended) ===
Open the monitor configuration.
Click the "Load BTP Apps" button.
The table will populate with the App Name, Subaccount (Org), and Space.
Activate the desired rows and configure specific thresholds.

=== Method 2: Wildcard Mode ===
App Name: Set to ''*''.
Subaccount / Space: Set to ''*'' to monitor everything, or enter a specific name to filter the wildcard discovery.

=== Settings Reference ===
^ Field ^ Description ^ Default ^ 
| Active | Enable/disable this configuration row | ''true'' | 
| App Name | Specific app name or '''' | ''*'' | 
| Subaccount | Filter by BTP Organization name | ''*'' | 
| Space | Filter by BTP Space name | ''*'' | 
| Discover All | Collect metrics for all apps in the subaccount | ''true'' | 
| Send Metrics | Enable/disable performance data storage | ''true'' | 
| State Monitor | Choose which state triggers an alarm (e.g., ''NOT_RUNNING'') | ''NOT_RUNNING'' |
| Memory Quota | Threshold for memory usage (e.g., ''G2W:80 W2M:90'') | ''80/90'' | 
| CPU Usage | Threshold for CPU usage (e.g., ''G2W:70 W2M:85'') | ''70/85'' |

===== Collected Metrics =====

Metrics are stored with the base name: ''promonitor.btp.cloud_foundry.applications.*''

^ Metric Key ^ Unit ^ Description ^ Tags ^ 
| running_instances | count | Healthy instances | app_name, org_name, space_name | 
| crashed_instances | count | Failed/Down instances | app_name, org_name, space_name | 
| memory_used_mb | MB | Memory consumed | app_name, org_name, space_name, instance# | 
| disk_used_mb | MB | Disk consumed | app_name, org_name, space_name, instance# | 
| cpu_usage_percent | % | CPU utilization | app_name, org_name, space_name, instance# |

===== Troubleshooting =====
"No cache → skipping monitoring": The monitor failed to load the application list. Check the connector URL and credentials.

HTTP 401/403: Verify the user has the Space Auditor role in BTP.

Metrics show 0 but app is running: Check if the app is using a process type other than ''web''. The monitor currently focuses on the ''web'' process stats.

Stale Data: The app list is cached for 60 minutes. If you added a new app, it might take an hour to appear unless you trigger "Load BTP Apps" or the cache expires.