Integrations nav

docs/Data-insights/Features/Integrations/Data/postgres.md

@@ -0,0 +1,124 @@
+# PostgreSQL
+
+Monitor PostgreSQL databases - connections, throughput, cache efficiency, and locks.
+
+Your database shows up alongside the rest of your telemetry, on a dashboard that is already built. You can see how Postgres is behaving - how many connections are in use, how much work it is doing, how well its cache is serving reads, and what is waiting on locks - next to the applications running against it.
+
+!!! info "What this integration does"
+    It provisions a **dashboard**. It does not collect anything itself and never connects to your database - the metrics come from **Grafana Alloy**, which has `postgres_exporter` built in. Until Alloy is collecting them, the dashboard is empty.
+
+Navigate to **Integrations** from the left-hand sidebar, then select **PostgreSQL**.
+
+---
+
+## Permission tiers
+
+PostgreSQL runs **Read-only**, which is the default and requires nothing - the metrics endpoint and signing key come from the service environment.
+
+Its one **capability** is **Dashboards**: installing it provisions the dashboard and nothing else.
+
+---
+
+## 1. Create a monitoring role
+
+The exporter only ever reads. Give it its own role rather than reusing an application login, and grant it `pg_monitor` - a built-in role that carries exactly the read access the statistics views need and nothing else:
+
+```sql
+CREATE USER opspilot_exporter WITH PASSWORD 'a strong password';
+GRANT pg_monitor TO opspilot_exporter;
+```
+
+Run that once per database server, not once per database.
+
+---
+
+## 2. Configure Alloy
+
+If you have no collector yet, the [Grafana Alloy guide](../../../../Monitor-your-data/OpenTelemetry/Shipping/Collector.md) covers installing one and getting an API key. That guide configures Alloy for OTLP; these metrics are Prometheus-format, so the components below are different, but the install and the API key are the same.
+
+```river
+prometheus.exporter.postgres "db" {
+  data_source_names = [
+    "postgresql://opspilot_exporter:PASSWORD@localhost:5432/postgres?sslmode=disable",
+  ]
+}
+
+prometheus.scrape "db" {
+  targets = prometheus.exporter.postgres.db.targets
+
+  scrape_interval = "30s"
+
+  forward_to = [prometheus.remote_write.opspilot.receiver]
+}
+
+prometheus.remote_write "opspilot" {
+  endpoint {
+    url = "https://api.fusionreactor.io/v1/metrics"
+
+    headers = {
+      "authorization" = sys.env("OPSPILOT_API_KEY"),
+    }
+  }
+}
+```
+
+A few things in there are worth understanding before you change them.
+
+**One connection string per server, not per database.** The exporter reports on every database on the server it connects to, so `postgres` as the connection database is conventional and sufficient. Listing several servers here gives you several instances on the dashboard; listing several databases on the same server gives you the same metrics several times over.
+
+**Put the password in an environment variable rather than the file.** Alloy reads the config in plain text, so:
+
+```river
+data_source_names = [
+  "postgresql://opspilot_exporter:" + sys.env("PG_EXPORTER_PASSWORD") + "@localhost:5432/postgres?sslmode=disable",
+]
+```
+
+`sslmode=disable` is for a local socket or a trusted network only. If Alloy reaches the database across anything else, use `sslmode=require` at minimum.
+
+**There is no `job_name` above, deliberately.** Alloy's built-in postgres component labels its own metrics `job="integrations/postgres"`, taking the name from the component, and setting `job_name` on the scrape does not override it. The dashboard reads that label, and also accepts `postgres` and `postgresql` for anyone scraping a standalone `postgres_exporter`. If you rename the component from `db` the label changes with it and the dashboard stops matching, so leave the name alone or add a relabel rule.
+
+**The instance label is the connection string, minus the credentials.** A server appears on the dashboard as `postgresql://host:5432/postgres` rather than as a hostname. The exporter strips the username, password, and query parameters before labeling, so nothing secret reaches your metrics store.
+
+---
+
+## 3. Confirm the data arrived
+
+In OpsPilot, open **Explore**, select the **Metrics** data source, and run:
+
+```promql
+pg_up
+```
+
+You should get one series per server, reading `1`. If that returns data, the dashboard will too.
+
+---
+
+## Troubleshooting
+
+**`pg_up` is 0.** Alloy is reaching the exporter but the exporter cannot reach Postgres. Check the credentials, that the host and port are right from where Alloy runs, and that `pg_hba.conf` allows the connection.
+
+**Nothing in Explore at all.** Check the Alloy UI on port `12345` - a failing component shows there with the error.
+
+**Permission errors in the Alloy log.** The role is missing `pg_monitor`. Some statistics views return no rows rather than failing, so the dashboard may be partly populated rather than empty.
+
+**The dashboard shows more databases than you expected.** Postgres' own `template0`, `template1`, and `postgres` databases are excluded from every panel. Anything else on the server appears, because the exporter reports on all of them.
+
+**Nothing about individual tables.** `pg_stat_user_tables` only covers the database the connection string names, which is why there is no per-table panel - see the integration's README for the detail.
+
+---
+
+## What is not here
+
+A few things this dashboard deliberately does not show:
+
+**Database uptime.** It needs the `postmaster` collector, which is off by default. There is a `process_start_time_seconds` in the exporter's output, but that is the exporter's own start time rather than the database's, so the dashboard reads neither.
+
+**Query-level statistics.** Which queries are slow, and how often they run, comes from the `pg_stat_statements` extension and a collector that is off by default. It is worth having when you are investigating something, but it is a diagnostic tool rather than a health signal, and it costs a series per distinct query shape.
+
+**Replication.** The metrics exist but need a replica to mean anything, and what you want to see differs enough between streaming replication, logical replication, and a managed service that one generic panel would mislead.
+
+---
+
+!!! question "Need more help?"
+    Contact support in the chat bubble and let us know how we can assist.

docs/Data-insights/Features/Integrations/Infrastructure/idrac.md

@@ -0,0 +1,179 @@
+# iDRAC
+
+Monitor Dell PowerEdge hardware health through iDRAC.
+
+Your servers' hardware shows up alongside the rest of your telemetry, on a dashboard that is already built - system health, sensors, power, storage, network, processors, and memory, read straight from each machine's baseboard management controller (BMC).
+
+!!! info "What this integration does"
+    It provisions a **dashboard**. It does not collect anything itself and never connects to your hardware. Unlike the [Docker](docker.md), [Unix](unix.md), and [Windows](windows.md) integrations, Alloy has no built-in collector for this one. You run `idrac_exporter` alongside Alloy, and it talks Redfish to each BMC. The same exporter works for HPE iLO and Lenovo XClarity, so a mixed estate needs only one of them. Until the exporter is running and Alloy is scraping it, the dashboard is empty.
+
+Navigate to **Integrations** from the left-hand sidebar, then select **iDRAC**.
+
+---
+
+## Permission tiers
+
+iDRAC runs **Read-only**, which is the default and requires nothing - the metrics endpoint and signing key come from the service environment.
+
+Its one **capability** is **Dashboards**: installing it provisions the dashboard and nothing else.
+
+---
+
+## 1. Create a read-only account on each BMC
+
+In the iDRAC web interface, add a local user with the **Read Only** role. The exporter only ever reads, so anything more is unnecessary exposure. Where user management sits in the menus varies between iDRAC generations - on iDRAC 9 it is under **iDRAC Settings**.
+
+If your BMCs are joined to Active Directory or LDAP you can use a directory account instead, as long as it has the read-only role on each machine.
+
+---
+
+## 2. Run the exporter
+
+Its configuration file lists the hosts it will talk to and the credentials for each:
+
+```yaml
+address: 0.0.0.0
+port: 9348
+timeout: 60
+
+hosts:
+  # One entry per BMC. The key is the address you will scrape it at.
+  192.168.1.21:
+    username: opspilot
+    password: <password>
+  192.168.1.22:
+    username: opspilot
+    password: <password>
+
+metrics:
+  system: true
+  sensors: true
+  power: true
+  storage: true
+  network: true
+  processors: true
+  memory: true
+```
+
+Then run it:
+
+```bash
+docker run -d --name idrac_exporter \
+  -p 127.0.0.1:9348:9348 \
+  -v /etc/prometheus/idrac.yml:/etc/prometheus/idrac.yml:ro \
+  ghcr.io/mrlhansen/idrac_exporter:latest
+```
+
+Two things above are deliberate, and both matter.
+
+**The port is published on localhost only.** That is the `127.0.0.1:` prefix on the `-p` flag - the exporter still listens on `0.0.0.0` inside the container, which it has to, or Docker could not forward to it at all. What changes is that Docker binds the host side to loopback rather than to every interface. Alloy scrapes it from the same host, so nothing else needs to reach it; published wide, anyone who can reach port `9348` can ask the exporter to scrape an address of their choosing. If you run the exporter directly rather than in a container, set `address: 127.0.0.1` in its config instead - there is no Docker layer to do it for you.
+
+**There is no `default:` entry.** The exporter's config allows one, as a fallback for any target not listed. With it, a request naming a host the exporter has never heard of makes it open a Redfish session to that host and send it the fallback account's username and password - so an attacker who can reach the exporter can have your BMC credentials delivered to a server they control. Listing each BMC explicitly means a request for anything else is simply refused.
+
+The seven metric groups above are the ones this dashboard reads, and every one of them is off by default - the exporter enables nothing unless asked. Leaving `processors` or `memory` out is worth avoiding in particular: the component health panels would then show green while a CPU or a DIMM was reporting Critical, and a failed DIMM is the most common fault on this hardware. Adding groups beyond these seven costs scrape time for data nothing displays; see the exporter's documentation for the full list.
+
+---
+
+## 3. Scrape it with Alloy
+
+If you have no collector yet, the [Grafana Alloy guide](../../../../Monitor-your-data/OpenTelemetry/Shipping/Collector.md) covers installing one and getting an API key. That guide configures Alloy for OTLP; these metrics are Prometheus-format, so the components below are different, but the install and the API key are the same.
+
+The exporter is a **multi-target** exporter: one instance serves many BMCs, and you tell it which one you want with a `target` parameter. That shapes the Alloy config more than it looks:
+
+```river
+// One entry per BMC. The address here is what the exporter connects to and
+// what identifies the machine on the dashboard.
+discovery.relabel "idrac" {
+  targets = [
+    { "__address__" = "192.168.1.21" },
+    { "__address__" = "192.168.1.22" },
+  ]
+
+  // Ask the exporter for this BMC...
+  rule {
+    source_labels = ["__address__"]
+    target_label  = "__param_target"
+  }
+
+  // ...keep the BMC's address as the instance label, so each machine is
+  // identifiable on the dashboard...
+  rule {
+    source_labels = ["__param_target"]
+    target_label  = "instance"
+  }
+
+  // ...and point the scrape itself at the exporter rather than the BMC.
+  rule {
+    target_label = "__address__"
+    replacement  = "localhost:9348"
+  }
+}
+
+prometheus.scrape "idrac" {
+  targets = discovery.relabel.idrac.output
+
+  job_name        = "idrac"
+  metrics_path    = "/metrics"
+  scrape_interval = "2m"
+  scrape_timeout  = "2m"
+
+  forward_to = [prometheus.remote_write.opspilot.receiver]
+}
+
+prometheus.remote_write "opspilot" {
+  endpoint {
+    url = "https://api.fusionreactor.io/v1/metrics"
+
+    headers = {
+      "authorization" = sys.env("OPSPILOT_API_KEY"),
+    }
+  }
+}
+```
+
+Three things in there matter more than they look.
+
+**The three relabel rules are what make several machines distinguishable.** Without them every BMC is scraped as `localhost:9348`, so the dashboard shows one machine no matter how many you have, with their readings overwriting each other. The rules take the BMC address, pass it to the exporter as the target, keep it as the instance label, and then redirect the actual HTTP request to the exporter.
+
+**`job_name = "idrac"` is required.** Every panel filters on it, because your metrics land in a store shared with everything else you send to OpsPilot. It matches the exporter's own documentation, so if you already scrape it you probably have this already.
+
+**The intervals are deliberately long, but not longer than five minutes.** The exporter collects on demand: each scrape opens a Redfish session and walks the BMC, which is slow hardware doing slow work. A minute is normal and several is possible on a machine with many drives, so scraping every 15 seconds would queue requests faster than the BMC can answer them.
+
+Two minutes is the balance. Going to five would be gentler still, but five minutes is also the query lookback window: samples would arrive exactly one lookback apart, and every cycle there would be a short gap where the previous sample has aged out and the next has not arrived. During it the point-in-time panels empty - and "Components not OK" would fall back to zero, which looks green rather than looking broken.
+
+---
+
+## 4. Confirm the data arrived
+
+In OpsPilot, open **Explore**, select the **Metrics** data source, and run:
+
+```promql
+idrac_system_health{job="idrac"}
+```
+
+You should get one series per machine. `0` is OK, `1` Warning, `2` Critical.
+
+---
+
+## Troubleshooting
+
+**Nothing in Explore.** Ask the exporter directly first, from the machine it runs on:
+
+```bash
+curl 'http://localhost:9348/metrics?target=192.168.1.21'
+```
+
+An error there is between the exporter and the BMC, and its own logs will say which. If that works but nothing reaches OpsPilot, the problem is in Alloy - check its UI on port `12345`.
+
+**"failed to instantiate new client".** The exporter cannot open a Redfish session. Usually the credentials, or a BMC with Redfish disabled - it is on by default on iDRAC 9, but worth checking in the iDRAC settings if the credentials are definitely right.
+
+**Every machine shows as one.** The relabel rules in step 3 are missing or wrong, so every scrape is labeled with the exporter's address rather than the BMC's. The Machines table at the bottom of the dashboard will show one row with an Endpoint of `localhost:9348`.
+
+**Scrapes time out.** Raise `scrape_timeout`, and turn off metric groups you do not need in the exporter's configuration. Storage is the slowest on a machine with many drives.
+
+**The drive life panel is empty.** Only SSDs report remaining endurance. Spinning disks do not, and are left out rather than shown at zero.
+
+---
+
+!!! question "Need more help?"
+    Contact support in the chat bubble and let us know how we can assist.

docs/Data-insights/Features/Integrations/SDKs/sdk-integrations.md

@@ -1,6 +1,6 @@
 # SDK Integrations
 
-The SDK integrations provision runtime dashboards and alert rules for applications instrumented with OpenTelemetry. Install one, instrument your application, and you have runtime monitoring in place without building it yourself.
+Most SDK integrations provision runtime dashboards and alert rules for applications instrumented with OpenTelemetry. Install one, instrument your application, and you have runtime monitoring in place without building it yourself.
 
 Navigate to **Integrations** from the left-hand sidebar and open the **SDKs** tab.
 
@@ -17,11 +17,15 @@ Each SDK integration installs one runtime dashboard per upstream metric-set vers
 | Go | 6 | 4 | `go_runtime_alerts` |
 | Node.js | 9 | 3 | `nodejs_runtime_alerts` |
 | Python | 5 | 5 | `python_runtime_alerts` |
+| PHP | 8 | 10 | `php_runtime_alerts` |
 
 The dashboard counts differ because each covers that language's full range of upstream metric-set versions. Java's 26 span thirteen Java-agent eras from v0.11.0 and thirteen semantic-convention sets from 1.9.0.
 
-!!! note "Ruby"
-    The Ruby OpenTelemetry SDK does not officially support metrics, so a Ruby integration cannot provide runtime dashboards. Ruby applications still send traces and span metrics, which Coworker can analyse.
+!!! note "PHP"
+    PHP's eight dashboards are four runtime and SDK-version dashboards plus four that cover third-party libraries, under the **Libraries** folder - these fill in once the matching library instrumentation is in place. Its ten alert rules split five for the runtime and five for the SDK's own export pipeline. Some runtime panels are conditional (OPcache, GC timing on PHP 8.3+, process CPU) and stay empty unless the service reports them; each rule stays silent where its metric is absent rather than firing on missing data. The **Installation guide** tab has the per-SDK-version detail.
+
+!!! note "SDKs without runtime dashboards"
+    **Ruby**, **Rust**, **C++**, **Swift**, and **Erlang** appear in the catalog but do not provision runtime dashboards or alert rules - their OpenTelemetry SDKs don't export the runtime metrics these dashboards are built on. The Ruby SDK, for example, does not officially support metrics. Applications in these languages still send traces and span metrics, which Coworker can analyze.
 
 ---
 

docs/Data-insights/Features/Integrations/Ticketing/jira.md

@@ -1,29 +1,23 @@
-# Jira Integration
+# Jira
 
-Connect OpsPilot to Jira to automatically create issues from alerts and incidents.
+Create, search, and link Jira issues from incidents and OpsPilot.
 
-!!! note "Legacy integration"
-    This page covers the **legacy** Jira integration, which is still available and still works. To find it, navigate to [Integrations](../../integrations.md) and switch on **Legacy**, at the right-hand end of the category tabs.
+!!! info "Coming soon"
+    Jira is listed in the integration catalog but is **not yet available to install**. This page describes what it will do once it ships - there is nothing to set up in the meantime.
 
-    A new Jira integration appears in the main integration catalog as **Coming soon**, and will replace this one.
-
-Navigate to **Integrations** from the left-hand sidebar, switch on **Legacy**, then select **Jira**.
+Navigate to **Integrations** from the left-hand sidebar, then select **Jira** to see its current status.
 
 ---
 
-## Setup
+## What it will do
 
-1. In OpsPilot, go to **Integrations**, switch on **Legacy**, and click **Jira**.
-2. Enter your Jira instance URL (e.g., `https://yourorg.atlassian.net`).
-3. Provide your Jira **email address** and an **API token**. You can generate an API token from your [Atlassian account settings](https://id.atlassian.com/manage-profile/security/api-tokens).
-4. Select the default **project** where issues should be created.
-5. Click **Save**.
+Once available, the Jira integration will let OpsPilot create, search, and link Jira issues from your incidents and from OpsPilot itself - so a situation or incident can become a tracked Jira ticket without leaving OpsPilot.
 
 ---
 
-## Using Jira with Incidents
+## Availability
 
-Once connected, OpsPilot can automatically open a Jira issue when an incident is created. Navigate to **Incidents** to configure this behaviour.
+Jira currently shows as **Coming soon** in the catalog, marked **Not yet available**. It declares no capabilities yet, and its permission tier is set when the integration is implemented. When it ships, this page will cover connecting your Jira instance and configuring issue creation.
 
 ---