Contoh instrumentasi Python

Dokumen ini menjelaskan cara mengubah aplikasi Python untuk mengumpulkan data metrik dan trace menggunakan framework OpenTelemetry open source, serta cara menulis log JSON terstruktur ke output standar. Dokumen ini juga memberikan informasi tentang aplikasi Python contoh yang dapat Anda instal dan jalankan. Aplikasi menggunakan framework web Flask dan dikonfigurasi untuk menghasilkan metrik, rekaman aktivitas, dan log.

Untuk mempelajari lebih lanjut instrumentasi, lihat dokumen berikut:

Tentang instrumentasi manual dan tanpa kode

Untuk bahasa ini, OpenTelemetry mendefinisikan instrumentasi tanpa kode sebagai praktik mengumpulkan telemetri dari library dan framework tanpa melakukan perubahan kode. Namun, Anda harus menginstal modul dan menetapkan variabel lingkungan.

Dokumen ini tidak menjelaskan instrumentasi tanpa kode. Untuk mengetahui informasi tentang topik tersebut, lihat Pelengkapan kode nol Python.

Untuk informasi umum, lihat Instrumentasi OpenTelemetry untuk Python.

Sebelum memulai

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Enable the APIs

Melengkapi aplikasi untuk mengumpulkan rekaman aktivitas, metrik, dan log

Untuk menginstrumentasi aplikasi Anda guna mengumpulkan data rekaman aktivitas dan metrik serta menulis JSON terstruktur ke output standar, lakukan langkah-langkah berikut seperti yang dijelaskan di bagian selanjutnya dalam dokumen ini:

  1. Mengonfigurasi OpenTelemetry
  2. Mengonfigurasi logging terstruktur

Mengonfigurasi OpenTelemetry

Aplikasi contoh ini dikonfigurasi untuk menggunakan OpenTelemetry Python SDK guna mengekspor trace dan metrik menggunakan protokol OTLP. Secara default, OpenTelemetry Python SDK menggunakan format W3C Trace Context untuk mempropagasi konteks trace, yang memastikan bahwa span memiliki hubungan induk-turunan yang benar dalam trace.

Contoh kode berikut menggambarkan modul Python untuk menyiapkan OpenTelemetry. Untuk melihat contoh lengkap, klik Lainnya, lalu pilih Lihat di 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)

    event_logger_provider = EventLoggerProvider(logger_provider)
    events.set_event_logger_provider(event_logger_provider)

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

Aplikasi Flask mengandalkan Gunicorn untuk melayani permintaan HTTP sesuai dengan rekomendasi dalam panduan Deploying to Production Flask. Gunicorn memulai beberapa salinan aplikasi Anda yang berjalan dalam proses pekerja independen untuk meningkatkan throughput. Untuk memastikan bahwa metrik dari proses pekerja tidak saling bertentangan, sebaiknya setiap proses pekerja menetapkan nilai unik untuk atribut resource service.instance.id. Salah satu cara untuk melakukannya adalah dengan menyertakan ID proses dalam service.instance.id. Untuk mengetahui informasi selengkapnya, lihat Konflik deret waktu.

Untuk mengetahui informasi dan opsi konfigurasi selengkapnya, lihat Instrumentasi OpenTelemetry Python.

Mengonfigurasi logging terstruktur

Untuk menulis log terstruktur yang ditautkan ke rekaman aktivitas, konfigurasi aplikasi Anda untuk menghasilkan log berformat JSON ke output standar dengan kunci yang berisi informasi rekaman aktivitas. Contoh kode berikut mengilustrasikan cara mengonfigurasi library logging standar untuk menghasilkan log terstruktur JSON menggunakan library python-json-logger, dan cara menggunakan paket opentelemetry-instrumentation-logging untuk menyertakan informasi rekaman aktivitas.

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],
    )

Konfigurasi sebelumnya mengekstrak informasi tentang rentang aktif dari pesan log, lalu menambahkan informasi tersebut sebagai atribut ke log terstruktur JSON. Atribut ini kemudian dapat digunakan untuk mengorelasikan log dengan rekaman aktivitas:

  • logging.googleapis.com/trace: Nama resource rekaman aktivitas yang terkait dengan entri log.
  • logging.googleapis.com/spanId: ID rentang dengan rekaman aktivitas yang terkait dengan entri log.
  • logging.googleapis.com/trace_sampled: Nilai kolom ini harus true atau false.

Untuk mengetahui informasi selengkapnya tentang kolom ini, lihat struktur LogEntry.

Menjalankan aplikasi contoh yang dikonfigurasi untuk mengumpulkan telemetri

Aplikasi contoh menggunakan format netral vendor, termasuk JSON untuk log dan OTLP untuk metrik dan rekaman aktivitas. Telemetri dari aplikasi dirutekan ke Google Cloud menggunakan OpenTelemetry Collector yang dikonfigurasi dengan pengekspor Google. Aplikasi ini menggunakan Flask untuk menayangkan permintaan HTTP, dan library requests untuk membuat permintaan HTTP. Untuk membuat metrik dan rekaman aktivitas untuk klien dan server HTTP, aplikasi contoh menginstal library instrumentasi opentelemetry-instrumentation-flask dan 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()

Aplikasi ini memiliki dua endpoint:

  • Endpoint /multi ditangani oleh fungsi multi. Generator beban di aplikasi mengirimkan permintaan ke endpoint /multi. Saat menerima permintaan, endpoint ini mengirimkan antara tiga hingga tujuh permintaan ke endpoint /single di server lokal.

    @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"

  • Endpoint /single ditangani oleh fungsi single. Saat menerima permintaan, endpoint ini akan tertidur selama beberapa saat, lalu merespons dengan string.

    @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"

Mendownload dan men-deploy aplikasi

Untuk menjalankan contoh, lakukan hal berikut:

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Meng-cloning repository

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

  3. Buka direktori contoh:

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

  4. Buat dan jalankan sampel:

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

    Jika Anda tidak menjalankan di Cloud Shell, jalankan aplikasi dengan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS yang mengarah ke file kredensial. Kredensial Default Aplikasi menyediakan file kredensial di $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

Melihat metrik Anda

Instrumentasi OpenTelemetry di aplikasi contoh menghasilkan metrik Prometheus yang dapat Anda lihat menggunakan Metrics Explorer:

  • Prometheus/http_server_duration_milliseconds/histogram mencatat durasi permintaan server dan menyimpan hasilnya dalam histogram.

  • Prometheus/http_client_duration_milliseconds/histogram mencatat durasi permintaan klien dan menyimpan hasilnya dalam histogram.

Untuk melihat metrik yang dihasilkan oleh aplikasi contoh, lakukan hal berikut:

  1. Di konsol Google Cloud , buka halaman  Metrics explorer:

    Buka Metrics explorer

    Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Monitoring.

  2. Di toolbar konsol Google Cloud , pilih project Google Cloud Anda. Untuk konfigurasi App Hub, pilih project host App Hub atau project pengelolaan folder yang mendukung aplikasi.
  3. Pada elemen Metrik, luaskan menu Pilih metrik, masukkan http_server di panel filter, lalu gunakan submenu untuk memilih jenis dan metrik resource tertentu:
    1. Di menu Active resources, pilih Prometheus Target.
    2. Di menu Active metric categories, pilih Http.
    3. Di menu Metrik aktif, pilih metrik.
    4. Klik Terapkan.
  4. Konfigurasi cara data dilihat.

    Jika pengukuran untuk metrik bersifat kumulatif, Metrics Explorer akan otomatis menormalisasi data yang diukur berdasarkan periode perataan, sehingga diagram menampilkan rasio. Untuk mengetahui informasi selengkapnya, lihat Jenis, tipe, dan konversi.

    Saat nilai bilangan bulat atau ganda diukur, seperti dengan dua metrik counter, Metrics Explorer akan otomatis menjumlahkan semua deret waktu. Untuk melihat data untuk rute HTTP /multi dan /single, tetapkan menu pertama entri Aggregation ke None.

    Untuk informasi selengkapnya tentang cara mengonfigurasi diagram, lihat Memilih metrik saat menggunakan Metrics Explorer.

Melihat trace Anda

Mungkin perlu waktu beberapa menit sebelum data rekaman aktivitas Anda tersedia. Misalnya, saat data rekaman aktivitas diterima oleh project Anda, Google Cloud Observability mungkin perlu membuat database untuk menyimpan data tersebut. Pembuatan database dapat memerlukan waktu beberapa menit dan selama periode tersebut, tidak ada data rekaman aktivitas yang tersedia untuk dilihat.

Untuk melihat data rekaman aktivitas, lakukan hal berikut:

  1. Di konsol Google Cloud , buka halaman Trace explorer:

    Buka Trace explorer

    Anda juga dapat menemukan halaman ini dengan menggunakan kotak penelusuran.

  2. Di bagian tabel halaman, pilih baris dengan nama rentang /multi.

  3. Pada diagram Gantt di panel Detail rekaman aktivitas, pilih rentang yang diberi label /multi.

    Panel yang menampilkan informasi tentang permintaan HTTP akan terbuka. Detail ini mencakup metode, kode status, jumlah byte, dan agen pengguna pemanggil.

  4. Untuk melihat log yang terkait dengan rekaman aktivitas ini, pilih tab Log & Peristiwa.

    Tab ini menampilkan log individual. Untuk melihat detail entri log, luaskan entri log. Anda juga dapat mengklik Lihat Log dan melihat log menggunakan Logs Explorer.

Untuk mengetahui informasi selengkapnya tentang cara menggunakan penjelajah Cloud Trace, lihat Menemukan dan menjelajahi rekaman aktivitas.

Melihat log

Dari Logs Explorer, Anda dapat memeriksa log, dan Anda juga dapat melihat rekaman aktivitas terkait, jika ada.

  1. Di konsol Google Cloud , buka halaman Logs Explorer:

    Buka Logs Explorer

    Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Logging.

  2. Temukan log dengan deskripsi handle /multi request.

    Untuk melihat detail log, luaskan entri log.

  3. Klik Traces pada entri log dengan pesan "handle /multi request", lalu pilih View trace details.

    Panel Trace details akan terbuka dan menampilkan rekaman aktivitas yang dipilih.

    Data log Anda mungkin tersedia beberapa menit sebelum data rekaman aktivitas Anda tersedia. Jika Anda mengalami error saat melihat data rekaman aktivitas baik dengan menelusuri rekaman aktivitas menurut ID atau dengan mengikuti langkah-langkah dalam tugas ini, tunggu satu atau dua menit, lalu coba lagi tindakan tersebut.

Untuk mengetahui informasi selengkapnya tentang cara menggunakan Logs Explorer, lihat Melihat log menggunakan Logs Explorer.

Langkah berikutnya