Python 檢測範例

本文說明如何使用 OpenTelemetry SDK 和 OpenTelemetry 收集器，對 Python 應用程式進行檢測，以收集追蹤記錄和指標資料。本文也說明如何將結構化 JSON 記錄寫入標準輸出。如要試用檢測功能，請下載並執行範例應用程式。這個應用程式使用 Flask 網路架構，並產生記錄、指標和追蹤記錄資料。

使用 OpenTelemetry 收集器時，請透過 SDK 和 SDK 的 OTLP 處理中匯出工具，檢測應用程式。這項儀表是中立的供應商。您也會部署 OpenTelemetry 收集器，接收來自程序內匯出工具的遙測資料，然後將該遙測資料匯出至 Google Cloud 專案。如要進一步瞭解收集器，請參閱「Google 打造的 OpenTelemetry 收集器」。

如果您的環境支援使用收集器，建議您使用 OpenTelemetry 收集器匯出遙測資料。在某些環境中，您必須使用程序內匯出工具，直接將資料傳送至Google Cloud 專案。如要瞭解程序內檢測，請參閱「從 Trace 匯出工具遷移至 OTLP 端點」。

如要進一步瞭解插樁，請參閱下列文件：

• 儀表化和可觀測性。
• 選擇插碼方式。

注意： 本文僅顯示工作應用程式的選定部分。 舉例來說，範例不會顯示匯入的套件清單。不過，您可以在 GitHub 上找到完整應用程式。如要查看完整範例，請按一下「更多」，然後選取「在 GitHub 上查看」。

關於手動和零程式碼檢測

對於這個語言，OpenTelemetry 將零程式碼檢測定義為從程式庫和架構收集遙測資料的做法，無需變更程式碼。不過，您必須安裝模組並設定環境變數。

本文不會說明零程式碼插碼。如要瞭解該主題，請參閱「Python 零程式碼檢測」。

如需一般資訊，請參閱 OpenTelemetry Instrumentation for Python。

事前準備

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

安裝 Google Cloud CLI。

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

建立或選取 Google Cloud 專案。

選取或建立專案所需的角色

• 選取專案：選取專案時，不需要具備特定 IAM 角色，只要您已獲授角色，即可選取任何專案。
• 建立專案：如要建立專案，您需要具備專案建立者角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

注意：如果您不打算保留在這項程序中建立的資源，請建立新專案，而不要選取現有專案。完成這些步驟後，您就可以刪除專案，並移除與該專案相關聯的所有資源。

• 建立 Google Cloud 專案：

  gcloud projects create PROJECT_ID

  將 PROJECT_ID 替換為您要建立的 Google Cloud 專案名稱。

• 選取您建立的 Google Cloud 專案：

  gcloud config set project PROJECT_ID

  將 PROJECT_ID 替換為 Google Cloud 專案名稱。

確認專案已啟用計費功能 Google Cloud 。

啟用 Cloud Logging、Cloud Monitoring、Cloud Trace 和 Telemetry API：

啟用 API 時所需的角色

如要啟用 API，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com

安裝 Google Cloud CLI。

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

建立或選取 Google Cloud 專案。

選取或建立專案所需的角色

• 選取專案：選取專案時，不需要具備特定 IAM 角色，只要您已獲授角色，即可選取任何專案。
• 建立專案：如要建立專案，您需要具備專案建立者角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

注意：如果您不打算保留在這項程序中建立的資源，請建立新專案，而不要選取現有專案。完成這些步驟後，您就可以刪除專案，並移除與該專案相關聯的所有資源。

• 建立 Google Cloud 專案：

  gcloud projects create PROJECT_ID

  將 PROJECT_ID 替換為您要建立的 Google Cloud 專案名稱。

• 選取您建立的 Google Cloud 專案：

  gcloud config set project PROJECT_ID

  將 PROJECT_ID 替換為 Google Cloud 專案名稱。

確認專案已啟用計費功能 Google Cloud 。

啟用 Cloud Logging、Cloud Monitoring、Cloud Trace 和 Telemetry API：

啟用 API 時所需的角色

如要啟用 API，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com

1. 如果您在 Cloud Shell、 Google Cloud資源或本機開發環境中執行範例，則本節列出的權限就足夠。對於正式版應用程式，通常是服務帳戶提供寫入記錄、指標和追蹤資料的憑證。

   如要取得範例應用程式寫入記錄、指標和追蹤資料所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

   • 記錄寫入者 (roles/logging.logWriter)
   • Monitoring 指標寫入者 (roles/monitoring.metricWriter)
   • Cloud 遙測資料追蹤記錄寫入者 (roles/telemetry.tracesWriter)

   如要取得查看記錄、指標和追蹤資料所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

   • 記錄檢視器 (roles/logging.viewer)
   • Monitoring 檢視者 (roles/monitoring.viewer)
   • Cloud Trace 使用者 (roles/cloudtrace.user)

   如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

   您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

檢測應用程式，收集追蹤記錄、指標和記錄

如要為應用程式進行檢測，以收集追蹤記錄和指標資料，並將結構化 JSON 寫入標準輸出，請按照本文件後續章節所述步驟操作：

1. 設定 OpenTelemetry
2. 設定結構化記錄

設定 OpenTelemetry

這個範例應用程式已設定為使用 OpenTelemetry Python SDK，透過 OTLP 通訊協定匯出追蹤記錄和指標。根據預設，OpenTelemetry Python SDK 會使用 W3C 追蹤脈絡格式傳播追蹤脈絡，確保追蹤記錄中的範圍具有正確的父項/子項關係。

以下程式碼範例說明如何使用 Python 模組設定 OpenTelemetry。如要查看完整範例，請按一下「更多」，然後選取「在 GitHub 上查看」。

def setup_opentelemetry() -> None:
    resource = Resource.create(
        attributes={
            # Use the PID as the service.instance.id to avoid duplicate timeseries
            # from different Gunicorn worker processes.
            SERVICE_INSTANCE_ID: f"worker-{os.getpid()}",
        }
    )
    # Set up OpenTelemetry Python SDK
    tracer_provider = TracerProvider(resource=resource)
    tracer_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
    trace.set_tracer_provider(tracer_provider)

    logger_provider = LoggerProvider(resource=resource)
    logger_provider.add_log_record_processor(BatchLogRecordProcessor(OTLPLogExporter()))
    logs.set_logger_provider(logger_provider)

    reader = PeriodicExportingMetricReader(OTLPMetricExporter())
    meter_provider = MeterProvider(metric_readers=[reader], resource=resource)
    metrics.set_meter_provider(meter_provider)

Flask 應用程式會依據 Flask「部署至正式環境」指南中的建議，透過 Gunicorn 處理 HTTP 要求。Gunicorn 會啟動多個應用程式副本，在獨立的工作站程序中執行，以提高輸送量。為確保工作站程序中的指標不會彼此衝突，建議每個工作站程序為 service.instance.id 資源屬性設定唯一值。其中一種做法是在 service.instance.id 中加入程序 ID。詳情請參閱「時間序列衝突」。

如要瞭解詳情和設定選項，請參閱 OpenTelemetry Python 檢測。

設定結構化記錄

如要編寫與追蹤記錄相關聯的結構化記錄，請將應用程式設定為將 JSON 格式的記錄輸出至標準輸出，並使用包含追蹤記錄資訊的金鑰。下列程式碼範例說明如何設定標準 logging 程式庫，使用 python-json-logger 程式庫輸出 JSON 結構化記錄，以及如何使用 opentelemetry-instrumentation-logging 套件納入追蹤資訊。

class JsonFormatter(jsonlogger.JsonFormatter):
    def formatTime(self, record: logging.LogRecord, datefmt: Optional[str] = None):
        # Format the timestamp as RFC 3339 with microsecond precision
        isoformat = datetime.fromtimestamp(record.created).isoformat()
        return f"{isoformat}Z"


def setup_structured_logging() -> None:
    LoggingInstrumentor().instrument()

    log_handler = logging.StreamHandler()
    formatter = JsonFormatter(
        "%(asctime)s %(levelname)s %(message)s %(otelTraceID)s %(otelSpanID)s %(otelTraceSampled)s",
        rename_fields={
            "levelname": "severity",
            "asctime": "timestamp",
            "otelTraceID": "logging.googleapis.com/trace",
            "otelSpanID": "logging.googleapis.com/spanId",
            "otelTraceSampled": "logging.googleapis.com/trace_sampled",
        },
    )
    log_handler.setFormatter(formatter)
    logging.basicConfig(
        level=logging.INFO,
        handlers=[log_handler],
    )

先前的設定會從記錄訊息中擷取有效範圍的相關資訊，然後將該資訊做為屬性新增至 JSON 結構化記錄。這些屬性可用於將記錄與追蹤記錄建立關聯：

• logging.googleapis.com/trace：與記錄項目相關聯的追蹤記錄資源名稱。
• logging.googleapis.com/spanId：與記錄項目相關聯的追蹤記錄時距 ID。
• logging.googleapis.com/trace_sampled：這個欄位的值必須是 true 或 false。

如要進一步瞭解這些欄位，請參閱 LogEntry 結構。

執行設定為收集遙測資料的範例應用程式

範例應用程式中的檢測功能使用與供應商無關的格式，例如記錄資料的 JSON，以及指標和追蹤資料的 OTLP。範例應用程式也會使用 Flask 處理 HTTP 要求，並使用 requests 程式庫發出 HTTP 要求。OpenTelemetry Collector 會使用 Google 匯出工具，將記錄和指標資料傳送至專案。並使用 Telemetry API (採用 OTLP) 將追蹤記錄資料傳送至專案。

如要為 HTTP 用戶端和伺服器產生指標和追蹤記錄，範例應用程式會安裝 opentelemetry-instrumentation-flask 和 opentelemetry-instrumentation-requests 檢測程式庫：

logger = logging.getLogger(__name__)

# Initialize OpenTelemetry Python SDK and structured logging
setup_opentelemetry()
setup_structured_logging()

app = Flask(__name__)

# Add instrumentation
FlaskInstrumentor().instrument_app(app)
RequestsInstrumentor().instrument()

這個應用程式有兩個端點：

• /multi 端點由 multi 函式處理。應用程式中的負載產生器會向 /multi 端點發出要求。這個端點收到要求時，會向本機伺服器上的 /single 端點傳送三到七個要求。

  @app.route("/multi")
  def multi():
      """Handle an http request by making 3-7 http requests to the /single endpoint."""
      sub_requests = randint(3, 7)
      logger.info("handle /multi request", extra={"subRequests": sub_requests})
      for _ in range(sub_requests):
          requests.get(url_for("single", _external=True))
      return "ok"
  
  

• /single 端點由 single 函式處理。這個端點收到要求時，會短暫休眠，然後以字串回應。

  @app.route("/single")
  def single():
      """Handle an http request by sleeping for 100-200 ms, and write the number of seconds slept as the response."""
      duration = uniform(0.1, 0.2)
      logger.info("handle /single request", extra={"duration": duration})
      time.sleep(duration)
      return f"slept {duration} seconds"
  
  

下載及部署應用程式

注意： 建議使用 Cloud Shell 執行範例應用程式。不過，如要在 Linux 或 Mac 上在本機執行範例應用程式，請略過下列操作說明的第一個步驟。

如要執行範例，請按照下列步驟操作：

1. 在 Google Cloud 控制台中啟用 Cloud Shell。

   啟用 Cloud Shell

   Google Cloud 主控台底部會開啟一個 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已針對您目前的專案設定好相關值。工作階段可能要幾秒鐘的時間才能初始化。

2. 複製存放區：

   git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-python
   

3. 前往範例目錄：

   cd opentelemetry-operations-python/samples/instrumentation-quickstart
   

4. 建構並執行範例：

   docker compose up --abort-on-container-exit
   

   如果不是在 Cloud Shell 上執行，請執行應用程式，並讓 GOOGLE_APPLICATION_CREDENTIALS 環境變數指向憑證檔案。應用程式預設憑證會在 $HOME/.config/gcloud/application_default_credentials.json 提供憑證檔案。

   # Set environment variables
   export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
   export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json"
   export USERID="$(id -u)"
   
   # Run
   docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit
   

查看指標

範例應用程式中的 OpenTelemetry 檢測會產生 Prometheus 指標，您可以使用 Metrics Explorer 查看這些指標：

• Prometheus/http_server_duration_milliseconds/histogram 記錄伺服器要求的持續時間，並將結果儲存在直方圖中。

• Prometheus/http_client_duration_milliseconds/histogram 記錄用戶端要求的持續時間，並將結果儲存在直方圖中。

如要查看範例應用程式產生的指標，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的 「指標探索器」頁面：

   前往 Metrics Explorer

   如果您是使用搜尋列尋找這個頁面，請選取子標題為「Monitoring」的結果。

2. 在 Google Cloud 控制台的工具列中，選取 Google Cloud 專案。 如要進行 App Hub 設定，請選取 App Hub 主專案或已啟用應用程式的資料夾管理專案。
3. 在「指標」元素中，展開「選取指標」選單， 在篩選列中輸入 http_server， 然後使用子選單選取特定資源類型和指標：
   1. 在「Active resources」(有效資源) 選單中，選取「Prometheus Target」(Prometheus 目標)。
   2. 在「使用中的指標類別」選單中，選取「Http」。
   3. 在「使用中的指標」選單中，選取指標。
   4. 按一下「套用」。

4. 如要新增篩選器，從查詢結果中移除時間序列，請使用「Filter」元素。

5. 設定資料的顯示方式。
   

   如果指標的測量值是累計值，Metrics Explorer 會自動以對齊週期將測量資料正規化，因此圖表會顯示比率。詳情請參閱「種類、型別和轉換」一文。

   測量整數或雙精度值時 (例如使用兩個 counter 指標)，Metrics Explorer 會自動加總所有時間序列。如要查看 /multi 和 /single HTTP 路由的資料，請將「Aggregation」(彙整) 項目的第一個選單設為「None」(無)。

   如要進一步瞭解如何設定圖表，請參閱「使用 Metrics Explorer 時選取指標」。

查看追蹤記錄

追蹤資料可能需要幾分鐘才會顯示。舉例來說，當專案收到追蹤記錄資料時，Google Cloud Observability 可能需要建立資料庫來儲存該資料。資料庫建立作業可能需要幾分鐘才能完成，這段期間內無法查看任何追蹤資料。

如要查看追蹤記錄資料，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的 「Trace Explorer」頁面：

   前往「Trace explorer」(Trace 探索工具)

   您也可以透過搜尋列找到這個頁面。

2. 在頁面的表格部分，選取跨度名稱為 /multi 的資料列。

3. 在「Trace details」(追蹤記錄詳細資料) 面板的甘特圖中，選取標示為 /multi 的時距。

   畫面上會開啟一個面板，顯示 HTTP 要求相關資訊。這些詳細資料包括方法、狀態碼、位元組數，以及呼叫者的使用者代理程式。

4. 如要查看與這項追蹤記錄相關聯的記錄檔，請選取「記錄檔和事件」分頁標籤。

   這個分頁會顯示個別記錄。如要查看記錄項目的詳細資料，請展開記錄項目。您也可以點選「查看記錄」，然後使用 Logs Explorer 查看記錄。

如要進一步瞭解如何使用 Cloud Trace 探索工具，請參閱「尋找及探索追蹤記錄」。

查看記錄檔

您可以在記錄檔探索器中檢查記錄，也可以查看相關聯的追蹤記錄 (如有)。

1. 前往 Google Cloud 控制台的 segment「Logs Explorer」頁面：

   前往「Logs Explorer」(記錄檔探索工具)

   如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。

2. 找出說明為 handle /multi request 的記錄。

   如要查看記錄詳細資料，請展開記錄項目。

3. 在含有「handle /multi request」訊息的記錄項目上，按一下「追蹤記錄」，然後選取「查看追蹤記錄詳細資料」。

   系統會開啟「Trace details」(追蹤記錄詳細資料) 面板，並顯示所選追蹤記錄。

   記錄資料可能比追蹤資料早幾分鐘提供。如果查看追蹤記錄資料時發生錯誤 (無論是依 ID 搜尋追蹤記錄，還是按照這項工作中的步驟操作)，請稍候一兩分鐘，然後重試。

如要進一步瞭解如何使用記錄檔探索工具，請參閱「使用記錄檔探索工具查看記錄檔」。

後續步驟

• OpenTelemetry
• OTLP 規格
• 結構化記錄
• 排解 Managed Service for Prometheus 的問題
• 排解 Cloud Trace 問題