Skip to main content

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 VariableDescription
ENV_OPS_TOKENAccess authentication key for the Ops Platform. Must be changed during first deployment
ENV_OPS_SUB_PATHOps 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_PORTInternal listening port of ops-server, default 8081; usually no change required
ENV_OPS_GATEWAY_PORTExternal 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 VariableDescription
ENV_K8S_MONITOR_MODEKubernetes 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_NAMECluster 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_NAMESPACENamespace 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 requires clusterMonitor and dbAdmin on the target database. The Ops Platform runs profile:1 to 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, not elastic. 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 VariableDescription
ENV_OPS_SD_URLAddress 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_TOKENAccess 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_HOSTHostname 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 VariableDescription
ENV_PROMETHEUS_RETENTIONPrometheus metrics retention. Default when not configured: 15d. Example: 30d
ENV_LOKI_RETENTIONLoki log retention. Default when not configured: 720h (30 days). Example: 360h
ENV_TEMPO_RETENTIONTempo trace retention. Default when not configured: 720h (30 days). Example: 360h

Observability Collection (Alloy)​

Environment VariableDescription
ENV_TEMPO_GRPC_URLgRPC address where alloy forwards trace data to Tempo. Example: http://ops-tempo:4317
ENV_PROMETHEUS_REMOTE_WRITE_URLremote_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_TOKENBearer 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_URLHTTP API address where alloy pushes logs to Loki. Example: http://ops-loki:3100/loki/api/v1/push
ENV_LOKI_PUSH_TOKENBearer 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 VariableDescription
ENV_S3_ENDPOINTS3-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_LOKIBucket 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_TEMPOBucket name for traces (Tempo). Example: mdis-tempo. Must be different from the Loki bucket, and must also be created in advance
ENV_S3_BUCKETOld 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_KEYS3 access key
ENV_S3_SECRET_KEYS3 secret key
ENV_S3_FORCE_PATH_STYLEBucket 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 VariableDescription
ENV_OPS_MONGODB_URIMongoDB 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_PREFIXUnified collection name prefix for the alert subsystem. Example: mdis_
ENV_ALERT_CRYPTO_KEYAES 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 VariableDescription
ENV_GATEWAY_DOCS_EXAMINEDMinimum 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_MSCapture interval in milliseconds, default 600000 (10 minutes). After triggering a slow query, wait for the next capture interval
ENV_GATEWAY_PROFILE_SLOW_MSslowms threshold in milliseconds that the Ops Platform sets for monitored databases, default 100
ENV_GATEWAY_LOG_EXPIRE_MSRetention 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 LocationVariablePurposeDefault
HAP/HDPENV_LOKI_URLWrite-side switch: whether logservice pushes logs to Loki. If not configured, the installer sets StoreInLoki to false, and service logs are not writtenEmpty (no writes)
Ops PlatformENV_LOKI_URLQuery-side address: where the Ops Platform reads logs fromhttp://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.