Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Migrasi ke Python OpenTelemetry
Panduan ini membantu Anda memigrasikan aplikasi Python dari X-Ray SDK OpenTelemetry ke instrumentasi. Ini mencakup pendekatan instrumentasi otomatis dan manual, dengan contoh kode untuk skenario umum.
**Topics**
+ [Solusi instrumentasi otomatis kode nol](#zero-code-python)
+ [Instrumen aplikasi Anda secara manual](#manual-instrumentation-python)
+ [Menelusuri inisialisasi pengaturan](#manual-instrumentation-python-tracing)
+ [Menelusuri permintaan yang masuk](#tracing-incoming-requests-python)
+ [AWS Instrumentasi SDK](#aws-sdk-instrumentation-python)
+ [Menginstrumentasi panggilan HTTP keluar melalui permintaan](#http-instrumentation-python)
+ [Dukungan instrumentasi untuk perpustakaan lain](#xray-migration-libraries-python)
+ [Membuat data jejak secara manual](#manual-trace-creation-python)
+ [Instrumentasi Lambda](#lambda-instrumentation-python)
## Solusi instrumentasi otomatis kode nol
Dengan X-Ray SDK, Anda harus memodifikasi kode aplikasi Anda untuk melacak permintaan. OpenTelemetry menawarkan solusi instrumentasi otomatis kode nol untuk melacak permintaan. Dengan OpenTelemetry, Anda memiliki opsi untuk menggunakan solusi instrumentasi otomatis kode nol untuk melacak permintaan.
**Kode nol dengan instrumentasi otomatis OpenTelemetry berbasis**
1. Menggunakan AWS Distro for OpenTelemetry (ADOT) Auto-instrumentation for Python — Untuk instrumentasi otomatis untuk aplikasi Python, lihat [Tracing](https://aws-otel.github.io/docs/getting-started/python-sdk/auto-instr) and Metrics with the Distro for Python Auto-Instrumentation. AWS OpenTelemetry
(Opsional) Anda juga dapat mengaktifkan Sinyal CloudWatch Aplikasi saat secara otomatis menginstrumentasi aplikasi Anda AWS dengan instrumentasi otomatis ADOT Python untuk memantau kesehatan aplikasi saat ini dan melacak kinerja aplikasi jangka panjang terhadap tujuan bisnis Anda. Sinyal Aplikasi memberi Anda tampilan menyatu dan terpusat aplikasi pada aplikasi, layanan, dan dependensi Anda, serta membantu Anda memantau dan menentukan prioritas kesehatan aplikasi.
1. [Menggunakan instrumentasi otomatis kode nol OpenTelemetry Python — Untuk instrumentasi otomatis dengan Python, lihat instrumentasi kode nol Python. OpenTelemetry ](https://opentelemetry.io/docs/zero-code/python/)
## Instrumen aplikasi Anda secara manual
Anda dapat secara manual instrumen aplikasi Anda menggunakan `pip` perintah.
------
#### [ With X-Ray SDK ]
```
pip install aws-xray-sdk
```
------
#### [ With OpenTelemetry SDK ]
```
pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-propagator-aws-xray
```
------
## Menelusuri inisialisasi pengaturan
------
#### [ With X-Ray SDK ]
Dalam X-Ray, global `xray_recorder` diinisialisasi dan digunakan untuk menghasilkan segmen dan sub-segmen.
------
#### [ With OpenTelemetry SDK ]
**catatan**
X-Ray Remote Sampling saat ini tidak tersedia untuk dikonfigurasi untuk OpenTelemetry Python. Namun, dukungan untuk X-Ray Remote Sampling saat ini tersedia melalui ADOT Auto-Instrumentation untuk Python.
Di OpenTelemetry, Anda perlu menginisialisasi global`TracerProvider`. Dengan menggunakan ini`TracerProvider`, Anda dapat memperoleh [Tracer](https://opentelemetry.io/docs/concepts/signals/traces/#tracer) yang dapat Anda gunakan untuk menghasilkan rentang di mana saja di aplikasi Anda. Disarankan agar Anda mengkonfigurasi komponen-komponen berikut:
+ `OTLPSpanExporter`- Diperlukan untuk mengekspor jejak ke CloudWatch OpenTelemetry Agen/Kolektor
+ Propagator AWS X-Ray — Diperlukan untuk menyebarkan Konteks Jejak ke AWS Layanan yang terintegrasi dengan X-Ray
```
from opentelemetry import (
trace,
propagate
)
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.propagators.aws import AwsXRayPropagator
# Sends generated traces in the OTLP format to an OTel Collector running on port 4318
otlp_exporter = OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")
# Processes traces in batches as opposed to immediately one after the other
span_processor = BatchSpanProcessor(otlp_exporter)
# More configurations can be done here. We will visit them later.
# Sets the global default tracer provider
provider = TracerProvider(active_span_processor=span_processor)
trace.set_tracer_provider(provider)
# Configures the global propagator to use the X-Ray Propagator
propagate.set_global_textmap(AwsXRayPropagator())
# Creates a tracer from the global tracer provider
tracer = trace.get_tracer("my.tracer.name")
# Use this tracer to create Spans
```
------
**Dengan ADOT Auto-instrumentasi untuk Python**
Anda dapat menggunakan instrumentasi otomatis ADOT untuk Python untuk mengkonfigurasi secara otomatis untuk aplikasi Python Anda. OpenTelemetry Dengan menggunakan instrumentasi otomatis ADOT, Anda tidak perlu membuat perubahan kode manual untuk melacak permintaan yang masuk, atau untuk melacak pustaka seperti klien SDK atau HTTP. AWS Untuk informasi selengkapnya, lihat [Menelusuri dan Metrik dengan AWS Distro untuk Instrumentasi Otomatis Python OpenTelemetry ](https://aws-otel.github.io/docs/getting-started/python-sdk/auto-instr).
Instrumentasi otomatis ADOT untuk Python mendukung:
+ X-Ray Remote Sampling melalui variabel lingkungan `export OTEL_TRACES_SAMPLER=xray`
+ Propagasi konteks jejak X-Ray (diaktifkan secara default)
+ Deteksi sumber daya (deteksi sumber daya untuk Amazon EC2, Amazon ECS, dan lingkungan Amazon EKS diaktifkan secara default)
+ Instrumentasi pustaka otomatis untuk semua OpenTelemetry instrumentasi yang didukung diaktifkan secara default. Anda dapat menonaktifkan secara selektif melalui variabel `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS ` lingkungan. (semua diaktifkan secara default)
+ Pembuatan manual Spans
**Dari plug-in layanan X-Ray hingga penyedia sumber daya OpenTelemetry AWS **
X-Ray SDK menyediakan plug-in yang dapat Anda tambahkan `xray_recorder` untuk menangkap informasi spesifik platform dari layanan yang dihosting seperti Amazon EC2, Amazon ECS, dan Elastic Beanstalk. Ini mirip dengan Penyedia Sumber Daya OpenTelemetry yang menangkap informasi sebagai atribut Sumber Daya. Ada beberapa Penyedia Sumber Daya yang tersedia untuk berbagai AWS platform.
+ Mulailah dengan menginstal paket AWS ekstensi, `pip install opentelemetry-sdk-extension-aws`
+ Konfigurasikan detektor sumber daya yang diinginkan. Contoh berikut menunjukkan cara mengonfigurasi penyedia sumber daya Amazon EC2 di SDK OpenTelemetry
```
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.extension.aws.resource.ec2 import (
AwsEc2ResourceDetector,
)
from opentelemetry.sdk.resources import get_aggregated_resources
provider = TracerProvider(
active_span_processor=span_processor,
resource=get_aggregated_resources([
AwsEc2ResourceDetector(),
]))
trace.set_tracer_provider(provider)
```
## Menelusuri permintaan yang masuk
------
#### [ With X-Ray SDK ]
X-Ray Python SDK mendukung kerangka aplikasi seperti Django, Flask, dan Bottle dalam melacak permintaan masuk untuk aplikasi Python berjalan pada mereka. Ini dilakukan dengan menambahkan aplikasi `XRayMiddleware` untuk setiap kerangka kerja.
------
#### [ With OpenTelemetry SDK ]
OpenTelemetry menyediakan instrumentasi untuk [Django](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/django/django.html) dan [Flask](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/flask/flask.html) melalui pustaka instrumentasi tertentu. Tidak ada instrumentasi untuk Botol yang tersedia di OpenTelemetry, aplikasi masih dapat dilacak dengan menggunakan Instrumentasi [OpenTelemetry WSGI](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/wsgi/wsgi.html).
Untuk contoh kode berikut, Anda memerlukan ketergantungan berikut:
```
pip install opentelemetry-instrumentation-flask
```
Anda harus menginisialisasi OpenTelemetry SDK dan mendaftarkan global TracerProvider sebelum menambahkan instrumentasi untuk kerangka kerja aplikasi Anda. Tanpa itu, operasi jejak akan terjadi`no-ops`. Setelah Anda mengonfigurasi global`TracerProvider`, Anda dapat menggunakan instrumentor untuk kerangka kerja aplikasi Anda. Contoh berikut menunjukkan aplikasi Flask.
```
from flask import Flask
from opentelemetry import trace
from opentelemetry.instrumentation.flask import FlaskInstrumentor
from opentelemetry.sdk.extension.aws.resource import AwsEc2ResourceDetector
from opentelemetry.sdk.resources import get_aggregated_resources
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
provider = TracerProvider(resource=get_aggregated_resources(
[
AwsEc2ResourceDetector(),
]))
processor = BatchSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# Creates a tracer from the global tracer provider
tracer = trace.get_tracer("my.tracer.name")
app = Flask(__name__)
# Instrument the Flask app
FlaskInstrumentor().instrument_app(app)
@app.route('/')
def hello_world():
return 'Hello World!'
if __name__ == '__main__':
app.run()
```
------
## AWS Instrumentasi SDK
------
#### [ With X-Ray SDK ]
X-Ray Python SDK melacak permintaan klien AWS SDK dengan menambal perpustakaan. `botocore` Untuk informasi selengkapnya, lihat [Menelusuri panggilan AWS SDK dengan X-Ray SDK untuk Python](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python-awssdkclients.html). Dalam aplikasi Anda, `patch_all()` metode ini digunakan untuk instrumen semua pustaka atau patch selektif menggunakan `boto3` pustaka `botocore` atau menggunakan. `patch((['botocore']))` Salah satu metode yang dipilih menginstrumentasikan semua klien Boto3 dalam aplikasi Anda dan menghasilkan sub-segmen untuk setiap panggilan yang dilakukan menggunakan klien ini.
------
#### [ With OpenTelemetry SDK ]
Untuk contoh kode berikut, Anda memerlukan ketergantungan berikut:
```
pip install opentelemetry-instrumentation-botocore
```
Gunakan [OpenTelemetry Botocore Instrumentation](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/botocore/botocore.html) secara terprogram untuk instrumen semua klien Boto3 dalam aplikasi Anda. Contoh berikut menunjukkan `botocore` instrumentasi.
```
import boto3
import opentelemetry.trace as trace
from botocore.exceptions import ClientError
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.resources import get_aggregated_resources
from opentelemetry.sdk.trace.export import (
BatchSpanProcessor,
ConsoleSpanExporter,
)
from opentelemetry.instrumentation.botocore import BotocoreInstrumentor
provider = TracerProvider()
processor = BatchSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# Creates a tracer from the global tracer provider
tracer = trace.get_tracer("my.tracer.name")
# Instrument BotoCore
BotocoreInstrumentor().instrument()
# Initialize S3 client
s3 = boto3.client("s3", region_name="us-east-1")
# Your bucket name
bucket_name = "my-example-bucket"
# Get bucket location (as an example of describing it)
try:
response = s3.get_bucket_location(Bucket=bucket_name)
region = response.get("LocationConstraint") or "us-east-1"
print(f"Bucket '{bucket_name}' is in region: {region}")
# Optionally, get bucket's creation date via list_buckets
buckets = s3.list_buckets()
for bucket in buckets["Buckets"]:
if bucket["Name"] == bucket_name:
print(f"Bucket created on: {bucket['CreationDate']}")
break
except ClientError as e:
print(f"Failed to describe bucket: {e}")
```
------
## Menginstrumentasi panggilan HTTP keluar melalui permintaan
------
#### [ With X-Ray SDK ]
X-Ray Python SDK melacak panggilan HTTP keluar melalui permintaan dengan menambal perpustakaan permintaan. Untuk informasi selengkapnya, lihat [Menelusuri panggilan ke layanan web HTTP hilir menggunakan X-Ray SDK untuk Python](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python-httpclients.html). Dalam aplikasi Anda, Anda dapat menggunakan `patch_all()` metode ini untuk instrumen semua pustaka atau dengan menambal pustaka permintaan secara selektif dengan menggunakan. `patch((['requests']))` Salah satu opsi instrumen `requests` perpustakaan, menghasilkan sub-segmen untuk setiap panggilan yang dilakukan. `requests`
------
#### [ With OpenTelemetry SDK ]
Untuk contoh kode berikut, Anda memerlukan ketergantungan berikut:
```
pip install opentelemetry-instrumentation-requests
```
Gunakan Instrumentasi OpenTelemetry Permintaan secara terprogram untuk menginstrumentasikan pustaka permintaan untuk menghasilkan jejak permintaan HTTP yang dibuat olehnya dalam aplikasi Anda. Untuk informasi selengkapnya, lihat [OpenTelemetry permintaan Instrumentasi](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/requests/requests.html). Contoh berikut menunjukkan instrumentasi `requests` perpustakaan.
```
from opentelemetry.instrumentation.requests import RequestsInstrumentor
# Instrument Requests
RequestsInstrumentor().instrument()
...
example_session = requests.Session()
example_session.get(url="https://example.com")
```
Atau, Anda juga dapat menginstruksikan `urllib3` pustaka yang mendasarinya untuk melacak permintaan HTTP:
```
# pip install opentelemetry-instrumentation-urllib3
from opentelemetry.instrumentation.urllib3 import URLLib3Instrumentor
# Instrument urllib3
URLLib3Instrumentor().instrument()
...
example_session = requests.Session()
example_session.get(url="https://example.com")
```
------
## Dukungan instrumentasi untuk perpustakaan lain
Anda dapat menemukan daftar lengkap instrumentasi Library yang didukung untuk OpenTelemetry Python di bawah [Pustaka, kerangka kerja, server aplikasi, dan file yang didukung](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md). JVMs
Atau, Anda dapat mencari OpenTelemetry Registry untuk mengetahui apakah OpenTelemetry mendukung instrumentasi. Lihat [Registry](https://opentelemetry.io/ecosystem/registry/) untuk mulai mencari.
## Membuat data jejak secara manual
Anda dapat membuat segmen dan sub-segmen menggunakan `xray_recorder` dalam aplikasi Python Anda. Untuk informasi selengkapnya, lihat [Menginstrumentasi kode Python](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python-middleware.html#xray-sdk-python-middleware-manual) secara manual. Anda juga dapat menambahkan anotasi dan metadata secara manual ke data jejak.
**Membuat bentang Dengan OpenTelemetry SDK**
Gunakan `start_as_current_span` API untuk memulai rentang dan atur untuk membuat rentang. Untuk contoh cara membuat bentang, lihat [Membuat bentang](https://opentelemetry.io/docs/languages/python/instrumentation/#creating-spans). Setelah rentang dimulai dan berada dalam lingkup saat ini, Anda dapat menambahkan lebih banyak informasi ke dalamnya dengan menambahkan atribut, peristiwa, pengecualian, tautan, dan sebagainya. Seperti bagaimana kita memiliki segmen dan sub-segmen dalam X-Ray, ada berbagai jenis bentang. OpenTelemetry Hanya rentang `SERVER` jenis yang dikonversi ke segmen X-Ray sementara yang lain diubah menjadi sub-segmen X-Ray.
```
from opentelemetry import trace
from opentelemetry.trace import SpanKind
import time
tracer = trace.get_tracer("my.tracer.name")
# Create a new span to track some work
with tracer.start_as_current_span("parent", kind=SpanKind.SERVER) as parent_span:
time.sleep(1)
# Create a nested span to track nested work
with tracer.start_as_current_span("child", kind=SpanKind.CLIENT) as child_span:
time.sleep(2)
# the nested span is closed when it's out of scope
# Now the parent span is the current span again
time.sleep(1)
# This span is also closed when it goes out of scope
```
**Menambahkan anotasi dan metadata ke jejak dengan SDK OpenTelemetry **
X-Ray Python SDK menyediakan terpisah APIs, `put_annotation` dan `put_metadata` untuk menambahkan anotasi dan metadata ke jejak. Di OpenTelemetry SDK, anotasi dan metadata hanyalah atribut pada rentang, ditambahkan melalui API. `set_attribute`
Atribut rentang yang Anda inginkan sebagai anotasi pada jejak ditambahkan di bawah kunci cadangan `aws.xray.annotations` yang nilainya adalah daftar pasangan anotasi nilai kunci. Semua atribut rentang lainnya menjadi metadata pada segmen atau sub-segmen yang dikonversi.
Selain itu, jika Anda menggunakan kolektor ADOT, Anda dapat mengonfigurasi atribut rentang mana yang harus dikonversi ke anotasi X-Ray `indexed_attributes` dengan menentukan konfigurasi kolektor.
Contoh di bawah ini menunjukkan cara menambahkan anotasi dan metadata ke jejak menggunakan SDK. OpenTelemetry
```
with tracer.start_as_current_span("parent", kind=SpanKind.SERVER) as parent_span:
parent_span.set_attribute("TransactionId", "qwerty12345")
parent_span.set_attribute("AccountId", "1234567890")
# This will convert the TransactionId and AccountId to be searchable X-Ray annotations
parent_span.set_attribute("aws.xray.annotations", ["TransactionId", "AccountId"])
with tracer.start_as_current_span("child", kind=SpanKind.CLIENT) as child_span:
# The MicroTransactionId will be converted to X-Ray metadata for the child subsegment
child_span.set_attribute("MicroTransactionId", "micro12345")
```
## Instrumentasi Lambda
Untuk memantau fungsi lambda Anda pada X-Ray, Anda mengaktifkan X-Ray dan menambahkan izin yang sesuai ke peran pemanggilan fungsi. Selain itu, jika Anda melacak permintaan hilir dari fungsi Anda, Anda akan menginstrumentasi kode dengan X-Ray Python SDK.
Dengan OpenTelemetry X-Ray, disarankan untuk menggunakan Lapisan AWS Lambda untuk OpenTelemetry [Sinyal Aplikasi](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-application-signals.html) dimatikan. Ini akan mengotomatiskan fungsi Anda dan akan menghasilkan rentang untuk pemanggilan fungsi dan permintaan hilir apa pun dari fungsi Anda. Selain melacak, jika Anda tertarik menggunakan Sinyal Aplikasi untuk memantau kesehatan fungsi Anda, lihat [Mengaktifkan aplikasi Anda di Lambda](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-LambdaMain.html).
+ Temukan ARN layer Lambda yang diperlukan untuk fungsi Anda dari [AWS Lambda](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-LambdaMain.html#Enable-Lambda-Layers) Layer dan tambahkan. OpenTelemetry ARNs
+ Tetapkan variabel lingkungan berikut untuk fungsi Anda.
+ `AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument`— Ini memuat instrumentasi otomatis untuk fungsi
+ `OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false`— Ini akan menonaktifkan pemantauan Sinyal Aplikasi
**Membuat bentang secara manual dengan instrumentasi Lambda**
Selain itu, Anda dapat menghasilkan rentang kustom dalam fungsi Anda untuk melacak pekerjaan. Anda dapat melakukannya dengan hanya menggunakan `opentelemetry-api` paket dalam hubungannya dengan AWS Lambda Layer OpenTelemetry untuk auto-instrumentasi.
1. Sertakan `opentelemetry-api` sebagai dependensi dalam fungsi Anda
1. Cuplikan kode berikut adalah contoh untuk menghasilkan rentang kustom
```
from opentelemetry import trace
# Get the tracer (auto‑configured by the AWS Lambda Layer for OpenTelemetry)
tracer = trace.get_tracer(__name__)
def handler(event, context):
# This span is a child of the layer's root span
with tracer.start_as_current_span("my-custom-span") as span:
span.set_attribute("key1", "value1")
span.add_event("custom-event", {"detail": "something happened"})
# Any logic you want to trace
result = some_internal_logic()
return {
"statusCode": 200,
"body": result
}
```