Environment Variables
The Ops Platform uses environment variables for its own access token, sub-path, data retention, and component connections. Configure them in ops.yaml for Docker Compose or in a ConfigMap for Kubernetes. Variables are grouped by purpose below; defaults apply when they are not configured.
Configure monitored hosts, middleware, and custom pages in Data Source Management. Version 1.4.x supported creating data sources at first startup through ENV_MYSQL_*, ENV_REDIS_*, and similar variables. Since 1.5.0 these variables are no longer read, and startup logs report them. Existing data sources remain unchanged after upgrading; historical configuration can be removed from ops.yaml.
Common/Gateway
| Environment Variable | Description |
|---|---|
| ENV_OPS_TOKEN | Access authentication key for the Ops Platform. Must be changed during first deployment |
| ENV_OPS_SUB_PATH | Ops Platform access sub-path. Once configured, use it for both direct access and reverse proxy access; with a reverse proxy, it must also match the proxy path. Example: /mdis |
| ENV_OPS_PORT | Internal listening port of ops-server, default 8081; usually no change required |
| ENV_OPS_GATEWAY_PORT | External gateway port, default 48881 |
Host Monitoring (Node Exporter)
Host data sources are not configured through environment variables. Add hosts on the "Data Sources" page using IP:59100 (fixed port 59100).
Docker Compose deployment hosts and Kubernetes cluster nodes already include ops-nodeagent (automatically listening on 59100). These hosts do not need to be registered again, and node_exporter does not need to be installed separately. Register only additional external hosts on the "Data Sources" page.
Cluster Monitoring (Kubernetes)
The Ops Platform supports Kubernetes cluster monitoring since 1.3.0 (nodes, containers, Pods, and cluster object status). See Kubernetes Cluster Monitoring for complete configuration.
| Environment Variable | Description |
|---|---|
| ENV_K8S_MONITOR_MODE | Kubernetes monitoring mode: off (default, disabled) / incluster (uses the ServiceAccount of the cluster where it runs to discover targets automatically). Kubernetes-form Ops Platform deployments are preset to incluster; when the Ops Platform is outside the cluster, this value is used by the collection components inside the monitored cluster. External pull mode (static) was removed in 1.5.3, so configuring it no longer takes effect |
| ENV_K8S_CLUSTER_NAME | Cluster identifier written as the origin_prometheus label on metrics. The Kubernetes panel uses this value to switch clusters. Default: default. In multi-cluster scenarios, assign different names to each cluster, such as prod-k8s/test-k8s. Avoid duplicates; using IP addresses is not recommended |
| ENV_K8S_KSM_NAMESPACE | Namespace where kube-state-metrics runs in incluster mode. Default: mdis-monitoring. Both Kubernetes manifests (single-file ops.yaml and PVC 11-configmap.yaml) set it to hap-ops. Their built-in kube-state-metrics also runs in hap-ops, so no change is required. Only collection components deployed inside monitored clusters use the default mdis-monitoring |
In incluster mode, no data source needs to be registered. ops-prometheus uses its own ServiceAccount to discover kubelet/cAdvisor/kube-state-metrics, and changes take effect in real time.
Middleware and Monitored Targets
No environment variables. MySQL/MongoDB/Redis/Kafka/Elasticsearch are all added in the UI "Data Sources" page. Each data source can select purposes:
- View Charts (
metrics): Included in metrics collection and displayed as charts in resource monitoring - Alert (
alert): Included in alert monitoring - Diagnostics (
diagnose, MongoDB only): Used as the target database for slow-query diagnostics. The account requiresclusterMonitoranddbAdminon the target database. The Ops Platform runsprofile:1to enable profiling
Exporter ports are assigned automatically by the Ops Platform and do not need to be managed manually.
Batch Import
The "Data Sources" page supports batch import through YAML or JSON. Download the YAML template, modify connection addresses, and upload it. We recommend clicking "Validate Only" first to check file format and probe each connection without writing data.
Import identifies data sources by "type + name". Entries with the same name are updated, and blank passwords retain the originals. Failed connection probes do not block import; abnormal entries are listed in the results.
Automation can call the API directly:
curl -X POST "http://部署服务器IP:48881/api/alert/sources/import" \
-H "Content-Type: application/yaml" \
--data-binary @datasources.yaml
Filling notes:
- For MySQL clusters, enter each node's actual address. Read/write splitting endpoints such as mysqlrouter collect only the routed backend and cannot cover all cluster member status.
- The built-in Elasticsearch username in private deployment is
md, notelastic. With an incorrect username, the collector process may run without obtaining metrics. - Include all MongoDB replica set members in the URI, separated by commas.
Data Source Service Discovery
agent pulls data sources that are enabled and have the metrics purpose from ops-server every 30 seconds, and starts/stops corresponding exporters as needed.
Prometheus scrape targets are also delivered by the registry and hot-loaded. Therefore, data source changes take effect immediately.
| Environment Variable | Description |
|---|---|
| ENV_OPS_SD_URL | Address used by ops-prometheus/agent to access the registry (ops-server), default http://gateway:8081. This is port 8081, where ops-server listens directly, rather than external gateway port 48881 (that is nginx and has no /api/sd route). Kubernetes Service must expose both ports |
| ENV_OPS_SD_TOKEN | Access token for the registry API. Keep it consistent on gateway, ops-prometheus, and agent. Empty means no validation (recommended only for Docker internal networks) |
| ENV_AGENT_SD_HOST | Hostname of the agent service, used by Prometheus to address exporters. Default: agent; usually no change required |
When a configured data source has no data, check the agent container logs first. Repeated [sd] 拉取 xxx 失败 messages indicate that agent cannot access the registry.
Common causes are ENV_OPS_SD_URL pointing to 48881, or a Kubernetes Service exposing only 48881 without 8081.
In this case, exporters cannot start and all middleware monitoring is empty.
Data Retention
| Environment Variable | Description |
|---|---|
| ENV_PROMETHEUS_RETENTION | Prometheus metrics retention. Default when not configured: 15d. Example: 30d |
| ENV_LOKI_RETENTION | Loki log retention. Default when not configured: 720h (30 days). Example: 360h |
| ENV_TEMPO_RETENTION | Tempo trace retention. Default when not configured: 720h (30 days). Example: 360h |
Observability Collection (Alloy)
| Environment Variable | Description |
|---|---|
| ENV_TEMPO_GRPC_URL | gRPC address where alloy forwards trace data to Tempo. Example: http://ops-tempo:4317 |
| ENV_PROMETHEUS_REMOTE_WRITE_URL | remote_write write address shared by two scenarios: 1. alloy reports the Ops Platform's own metrics and can connect directly inside the same cluster, for example http://ops-prometheus:9090/prometheus/server/api/v1/write; 2. collection components in other Kubernetes clusters push metrics back to the Ops Platform and must use the gateway external port with token, for example http://<运维平台地址>:30881/mdis/prometheus/server/api/v1/write (Ops Platform ops-prometheus is ClusterIP and cannot be accessed from outside the cluster on :9090) |
| ENV_PROMETHEUS_REMOTE_WRITE_TOKEN | Bearer token used when the previous item goes through the gateway. Fill in the Ops Platform ENV_OPS_TOKEN. If omitted, the gateway returns 401, visible only in collection-side logs while the UI only appears as "No Data". Direct :9090 access does not need it |
| ENV_LOKI_PUSH_URL | HTTP API address where alloy pushes logs to Loki. Example: http://ops-loki:3100/loki/api/v1/push |
| ENV_LOKI_PUSH_TOKEN | Bearer token for log push. Required only when the collector is in another cluster and pushes through the Ops Platform gateway (fill in the Ops Platform ENV_OPS_TOKEN). Leave empty when directly connecting to ops-loki inside the cluster. If omitted while using the gateway, it returns 401 and is visible only in collection-side logs |
Log Storage Backend (Loki S3/MinIO, Optional)
When not configured, Loki uses the local file system for storage.
| Environment Variable | Description |
|---|---|
| ENV_S3_ENDPOINT | S3-compatible storage endpoint. The host:port format is recommended, such as minio:9000. Tencent Cloud COS example: cos.ap-hongkong.myqcloud.com (without the bucket prefix). The Tempo startup script automatically strips protocol prefixes. For protocol handling and supported storage, see Object Storage Integration |
| ENV_S3_BUCKET_LOKI | Bucket name for logs (Loki). Example: mdis-loki. Create this bucket in object storage before deployment. If the bucket does not exist, Loki reports NoSuchBucket and restarts repeatedly |
| ENV_S3_BUCKET_TEMPO | Bucket name for traces (Tempo). Example: mdis-tempo. Must be different from the Loki bucket, and must also be created in advance |
| ENV_S3_BUCKET | Old generic bucket name retained only for existing deployment compatibility (used only when the two variables above are both unset). Do not use it for new deployments: it is passed to both Loki and Tempo, and sharing a bucket prevents Tempo from starting |
| ENV_S3_ACCESS_KEY | S3 access key |
| ENV_S3_SECRET_KEY | S3 secret key |
| ENV_S3_FORCE_PATH_STYLE | Bucket addressing mode. true (default) = path-style, suitable for MinIO/UCloud US3. Tencent Cloud COS/Alibaba Cloud OSS support only virtual-host and must be set to false. Loki (AWS SDK) and Tempo (minio-go, internally mapped to forced DNS bucket_lookup_type) share this switch |
Alert Subsystem (Since 1.4.0)
Ops Platform 1.4.0 includes a self-developed alert subsystem. Alert configuration data (rules/status/history/notification channels/data sources) is stored in an independent ops-mongo container and is completely decoupled from monitored business MongoDB.
| Environment Variable | Description |
|---|---|
| ENV_OPS_MONGODB_URI | MongoDB connection address for the alert subsystem's own storage. Defaults to the built-in ops-mongo container. Example: mongodb://ops-mongo:27017 |
| ENV_MONGODB_COLLECTION_PREFIX | Unified collection name prefix for the alert subsystem. Example: mdis_ |
| ENV_ALERT_CRYPTO_KEY | AES encryption key used before data source credentials (password/URI) are written to the database. Must be changed to a random string during first deployment and kept safe. After changing the key, saved credentials cannot be decrypted and must be re-entered |
Alert notification channels (Feishu/DingTalk/WeCom/email/custom Webhook) are configured in the Ops Platform UI under "Alerts → Notification Channels" and are no longer configured through environment variables. SMTP server information for email channels is also filled in on that page.
Slow Query Diagnostics Tuning (Optional)
Adjust MongoDB slow-query capture sensitivity. Defaults are suitable for production. In test environments, lower the first two items if you need easier reproduction. See Slow Query Analysis for the complete description of the four capture conditions.
| Environment Variable | Description |
|---|---|
| ENV_GATEWAY_DOCS_EXAMINED | Minimum number of documents examined before a query is recorded. Default 100000. Queries that are slow but examine fewer documents are not recorded |
| ENV_GATEWAY_CAPTURE_INTERVAL_MS | Capture interval in milliseconds, default 600000 (10 minutes). After triggering a slow query, wait for the next capture interval |
| ENV_GATEWAY_PROFILE_SLOW_MS | slowms threshold in milliseconds that the Ops Platform sets for monitored databases, default 100 |
| ENV_GATEWAY_LOG_EXPIRE_MS | Retention duration of slow-query history in the Ops Platform's own database, in milliseconds. Default 604800000 (7 days) |
Configure these on the gateway service. One fixed condition is not configurable: the same query fingerprint must appear at least 50 times within the last 120 minutes.
Service Log Ingestion
"Service Logs" queries logs pushed by HAP/HDP microservices to Loki.
| Configuration Location | Variable | Purpose | Default |
|---|---|---|---|
| HAP/HDP | ENV_LOKI_URL | Write-side switch: whether logservice pushes logs to Loki. If not configured, the installer sets StoreInLoki to false, and service logs are not written | Empty (no writes) |
| Ops Platform | ENV_LOKI_URL | Query-side address: where the Ops Platform reads logs from | http://ops-loki:3100; no change required in standard deployment |
The two variables have the same name but different purposes. If the "Service Logs" page has no content, configure the HAP/HDP service-side variable, using a reachable address for the Ops Platform Loki
(for example, http://运维平台主机IP:3100), and restart the corresponding product services after configuration.