Python application monitoring-Container Service for Kubernetes(ACK)-阿里云帮助中心

For Python applications deployed in ACK clusters, such as web applications built with frameworks like Django, Flask, and FastAPI, or AI and LLM applications developed using LlamaIndex and Langchain, you can use Application Real-Time Monitoring Service (ARMS) to monitor application performance. To enable monitoring, install the ack-onepilot component and modify your Dockerfile. This enables features such as application topology, tracing, API call analysis, anomaly detection, and detailed tracking of large model interactions.

Prerequisites

A namespace is created. For more information, see Manage namespaces and resource quotas. This topic uses the arms-demo namespace as an example.
The Python runtime is version 3.8 or later.
ARMS is compatible with Python 3.8 and later. Connection issues may occur if you use an earlier version.
Activate ARMS.
ARMS is an application performance management (APM) service provided by Alibaba Cloud. For more information about application monitoring, see What is Application Real-Time Monitoring Service (ARMS)? and What is application monitoring?.

Step 1: Install the ack-onepilot component

Important

The legacy arms-pilot component is no longer maintained. ack-onepilot is its replacement and is fully compatible -- migration requires no changes to your application configuration. For migration steps, see Uninstall arms-pilot and install ack-onepilot.

Log on to the ACK console. In the left navigation pane, click Clusters.
On the Clusters page, click the name of your cluster. In the left navigation pane, click Components and Add-ons .
In the Logs and Monitoring section, find the ack-onepilot add-on and click Install on the add-on card.
Note
Make sure that the version of ack-onepilot is 3.2.4 or later. By default, the ack-onepilot component supports up to 1,000 pods. For every 1,000 pods that exceed this limit, increase the CPU resources for ack-onepilot by 0.5 cores and the memory resources by 512 MB.
After the installation is complete, you can upgrade, configure, or uninstall the ack-onepilot add-on on the Add-ons page.

Step 2: Authorize ARMS to access resources

ARMS uses addon.arms.token for password-free authorization. Most ACK managed clusters include this secret by default. Some older clusters may not.

Check whether your cluster has the token:

Check for the addon.arms.token secret in the cluster

Log on to the ACK console. In the left navigation pane, click Clusters.
On the Clusters page, click the name of the target cluster. In the left navigation pane, choose Configurations > Secrets.
Select kube-system from the Namespace drop-down list and check whether addon.arms.token exists.

If the token is missing, grant permissions manually:

Log on to the ACK console. In the left navigation pane, click Clusters.
On the Clusters page, click the name of the target cluster. In the left navigation pane, click Cluster Information.
On the Basic Information tab, under Cluster Resources, click the link next to Worker RAM Role.
On the Permissions tab, click Grant Permission.
Select the AliyunARMSFullAccess policy and click Grant permissions.

If your cluster is connected to an Elastic Container Instance (ECI), go to the RAM Quick Authorization page and complete the authorization. Then restart the pods created for ack-onepilot.

Step 3: Integrate the ARMS Python agent into your Dockerfile

Modify your Dockerfile to integrate the ARMS Python agent and use it to start your Python application.

Install the agent installer from PyPI:
```
   RUN pip3 install aliyun-bootstrap
```
Install the agent. Replace <region-id> with your Alibaba Cloud region ID (for example, cn-hangzhou):
Note
To install a specific agent version, run: aliyun-bootstrap -a install -v <version> For all released versions, see Python agent release notes.
```
   RUN ARMS_REGION_ID=<region-id> aliyun-bootstrap -a install
```
Update the startup command to use the aliyun-instrument prefix:
```
   CMD ["aliyun-instrument", "python", "app.py"]
```
Build the image.

The following is a complete Dockerfile example:

Before:

FROM docker.m.daocloud.io/python:3.10

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY ./app.py /app/app.py
EXPOSE 8000
CMD ["python", "app.py"]

After (with ARMS agent):

FROM docker.m.daocloud.io/python:3.10

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Install the ARMS Python agent
RUN pip3 install aliyun-bootstrap \
    && ARMS_REGION_ID=<region-id> aliyun-bootstrap -a install

COPY ./app.py /app/app.py
EXPOSE 8000

# Start the application with the ARMS agent
CMD ["aliyun-instrument", "python", "app.py"]

Step 4: Enable ARMS monitoring

Log on to the ACK console. In the left navigation pane, click Clusters.
On the Clusters page, click the name of your cluster. In the left navigation pane, click Workloads > Deployments.
On the Deployments page, find your application and click > Edit YAML in the Actions column.

Add the following labels under spec.template.metadata: Replace <app-name> with a descriptive name for your application, such as my-python-service.

Important

If you use ack-onepilot later than 5.0.0 but have already installed the agent manually in your Dockerfile, disable auto-injection by adding this label: ``yaml armsAutoInstrumentationEnable: "off" ``

   labels:
     aliyun.com/app-language: python       # Required. Identifies this as a Python application.
     armsPilotAutoEnable: 'on'             # Enables ARMS monitoring.
     armsPilotCreateAppName: "<app-name>"  # Display name in the ARMS console.

The following code provides a complete YAML template to create a Deployment and enable application monitoring:

Complete YAML sample

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: arms-python-client
  name: arms-python-client
  namespace: arms-demo
spec:
  progressDeadlineSeconds: 600
  replicas: 1
  revisionHistoryLimit: 10
  selector:
    matchLabels:
      app: arms-python-client
  strategy:
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 25%
    type: RollingUpdate
  template:
    metadata:
      labels:
        app: arms-python-client
        aliyun.com/app-language: python # Required. Specifies the application language as Python.
        armsPilotAutoEnable: 'on'
        armsPilotCreateAppName: "arms-python-client"    # The application's display name in the ARMS console.
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/arms-default/python-agent:arms-python-client
          imagePullPolicy: Always
          name: client
          resources:
            requests:
              cpu: 250m
              memory: 300Mi
          terminationMessagePath: /dev/termination-log
          terminationMessagePolicy: File
      dnsPolicy: ClusterFirst
      restartPolicy: Always
      schedulerName: default-scheduler
      securityContext: {}
      terminationGracePeriodSeconds: 30
---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: arms-python-server
  name: arms-python-server
  namespace: arms-demo
spec:
  progressDeadlineSeconds: 600
  replicas: 1
  revisionHistoryLimit: 10
  selector:
    matchLabels:
      app: arms-python-server
  strategy:
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 25%
    type: RollingUpdate
  template:
    metadata:
      labels:
        app: arms-python-server
        aliyun.com/app-language: python # Required. Specifies the application language as Python.
        armsPilotAutoEnable: 'on'
        armsPilotCreateAppName: "arms-python-server"    # The application's display name in the ARMS console.
    spec:
      containers:
        - env:
          - name: CLIENT_URL
            value: 'http://arms-python-client-svc:8000'
          image: registry.cn-hangzhou.aliyuncs.com/arms-default/python-agent:arms-python-server
          imagePullPolicy: Always
          name: server
          resources:
            requests:
              cpu: 250m
              memory: 300Mi
          terminationMessagePath: /dev/termination-log
          terminationMessagePolicy: File
      dnsPolicy: ClusterFirst
      restartPolicy: Always
      schedulerName: default-scheduler
      securityContext: {}
      terminationGracePeriodSeconds: 30
---
apiVersion: v1
kind: Service
metadata:
  labels:
    app: arms-python-server
  name: arms-python-server-svc
  namespace: arms-demo
spec:
  internalTrafficPolicy: Cluster
  ipFamilies:
    - IPv4
  ipFamilyPolicy: SingleStack
  ports:
    - name: http
      port: 8000
      protocol: TCP
      targetPort: 8000
  selector:
    app: arms-python-server
  sessionAffinity: None
  type: ClusterIP
---
apiVersion: v1
kind: Service
metadata:
  name: arms-python-client-svc
  namespace: arms-demo
spec:
  internalTrafficPolicy: Cluster
  ipFamilies:
    - IPv4
  ipFamilyPolicy: SingleStack
  ports:
    - name: http
      port: 8000
      protocol: TCP
      targetPort: 8000
  selector:
    app: arms-python-client
  sessionAffinity: None
  type: ClusterIP

Step 5: View monitoring details

After about one minute, log on to the ARMS console. In the left-side navigation pane, choose Application Monitoring > Applications to view your Python application and its reported data.
In the application list, you can see the connected arms-python-client application and its metrics, such as requests per second, error rate, and average response time.
Click the Application Name to go to the application monitoring page in the ARMS console and view detailed monitoring information. For more information, see Application overview.

(Optional) Step 6: Release resources

If you no longer need to monitor your Python application with ARMS, you can uninstall the ARMS Python agent to stop monitoring. For more information, see Uninstall the Python agent.