OpenTelemetry チュートリアル: サンプル Python アプリをインストゥルメントする

デモアプリケーションをダウンロードする

以下を実行してデモ アプリをダウンロードします。

git clone https://github.com/newrelic/newrelic-opentelemetry-examples.git

必要なライブラリをインストールする

必要なライブラリを追加するには:

1. このチュートリアルの開始点として、インストルメント化されていないアプリのアプリケーション ディレクトリに移動します。このチュートリアルが終わるまでに、コードは Instrumented ディレクトリにあるもののようになっているはずです。

   cd newrelic-opentelemetry-examples/getting-started-guides/python/Uninstrumented

   コピー

2. Uninstrumented ディレクトリに仮想環境を作成してアクティブ化します。

   • マックOS：

     python3 -m venv venv
     source venv/bin/activate

     コピー

   • パワーシェル：

     python -m venv venv
     .\venv\Scripts\Activate.ps1

     コピー

3. 以下をインストールします。

   pip install opentelemetry-api
   pip install opentelemetry-sdk
   pip install flask
   pip install opentelemetry-instrumentation-logging
   pip install opentelemetry-instrumentation-flask
   pip install opentelemetry-exporter-otlp
   pip install opentelemetry-distro

   コピー

SDKを設定する

1. app.pyで、以下の強調表示された行をtop of the fileに追加します。 必要に応じて、カスタムアトリビュートenvironmentの値を変更します。

   ##########################
   # OpenTelemetry Settings #
   ##########################
   from opentelemetry.sdk.resources import Resource
   import uuid
   
   OTEL_RESOURCE_ATTRIBUTES = {
       "service.instance.id": str(uuid.uuid1()),
       "environment": "local"
   }
   
   from flask import Flask, jsonify, request
   
   app = Flask(__name__)

   コピー

2. 以下の 環境変数リファレンス セクション に移動して、エクスポートする必要がある変数を確認してから、インストルメンテーション ライブラリを追加する次の手順に進みます。

インストルメンテーション ライブラリの追加: トレース

app.pyで、追加した OpenTelemetry Settings の後に以下を挿入します。

##########
# Traces #
##########
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.trace.status import Status, StatusCode

# Initialize tracing and an exporter that can send data to an OTLP endpoint
# SELECT * FROM Span WHERE instrumentation.provider='opentelemetry'
trace.set_tracer_provider(TracerProvider(resource=Resource.create(OTEL_RESOURCE_ATTRIBUTES)))
trace.get_tracer_provider().add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))

インストルメンテーション ライブラリの追加: メトリクス

app.py で、ステップ D で追加した Traces セクションの後に次の行を追加します。

###########
# Metrics #
###########
from opentelemetry import metrics
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter

# Initialize metering and an exporter that can send data to an OTLP endpoint
# SELECT count(`http.server.active_requests`) FROM Metric FACET `service.name` TIMESERIES
metrics.set_meter_provider(MeterProvider(resource=Resource.create(OTEL_RESOURCE_ATTRIBUTES), metric_readers=[PeriodicExportingMetricReader(OTLPMetricExporter())]))
metrics.get_meter_provider()
fib_counter = metrics.get_meter("opentelemetry.instrumentation.custom").create_counter("fibonacci.invocations", unit="1", description="Measures the number of times the fibonacci method is invoked.")

インストルメンテーション ライブラリの追加: ログ

app.pyの Metrics セクションの後に以下を追加します。これにより、ログ モジュールがインポートされ、 basicConfig ログ レベルが DEBUGに設定されます。

########
# Logs # - OpenTelemetry Logs are still in the experimental state, so function names may change in the future
########
import logging
logging.basicConfig(level=logging.DEBUG)

from opentelemetry import _logs
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter

# Initialize logging and an exporter that can send data to an OTLP endpoint by attaching OTLP handler to root logger
# SELECT * FROM Log WHERE instrumentation.provider='opentelemetry'
_logs.set_logger_provider(LoggerProvider(resource=Resource.create(OTEL_RESOURCE_ATTRIBUTES)))
logging.getLogger().addHandler(LoggingHandler(logger_provider=_logs.get_logger_provider().add_log_record_processor(BatchLogRecordProcessor(OTLPLogExporter()))))

Flask インストゥルメンテーションを追加

app.py の Logs セクションの後に、以下の強調表示された行を追加します。これは、分散トレースとログインコンテキストのスパンをリンクするのに役立ちます。

#####################
# Flask Application #
#####################
from flask import Flask, jsonify, request
from opentelemetry.instrumentation.flask import FlaskInstrumentor

app = Flask(__name__)
FlaskInstrumentor().instrument_app(app)

カスタム トレース インストルメンテーション: カスタム スパンの作成

必要なスパンを作成できます。特定の操作に関する属性でスパンに注釈を付けるのはあなた次第です。設定した属性は、結果や操作のプロパティなど、追跡している特定の操作に関する追加のコンテキストを提供します。

app.pyに、以下の強調表示された行を挿入して、次の処理を行う /fibonacci という新しいスパンを開始します。

• このメソッドの実行に関するデータをキャプチャします

• ユーザーのリクエストから n の値を格納する属性を設定します

  @app.route("/fibonacci")
  
  @trace.get_tracer("opentelemetry.instrumentation.custom").start_as_current_span("/fibonacci")
  def fibonacci():
      args = request.args
      x = int(args.get("n"))
      error_message = "n must be 1 <= n <= 90."
      trace.get_current_span().set_attribute("fibonacci.n", x)
  
      try:
          assert 1 <= x <= 90
          array = [0, 1]
          for n in range(2, x + 1):
              array.append(array[n - 1] + array[n - 2])
  
          trace.get_current_span().set_attribute("fibonacci.result", array[x])
          return jsonify(n=x, result=array[x])
  
      except AssertionError:
          return jsonify({"message": error_message})
  
  app.run(host='0.0.0.0', port=8080)

  コピー

カスタム トレース インストルメンテーション: 例外を記録する

例外が発生したときに、例外を記録したい場合があります。スパンステータスの設定と併せてこれを行うことをお勧めします。

1. 例外が発生したときにスパンのステータス コードをERRORに設定するには、手順Dで追加したopentelemetry.trace.status packageのStatusモジュールとStatusCodeモジュールを使用します。

   ##########
   # Traces #
   ##########
   from opentelemetry import trace
   from opentelemetry.sdk.trace import TracerProvider
   from opentelemetry.sdk.trace.export import BatchSpanProcessor
   from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
   from opentelemetry.trace.status import Status, StatusCode

   コピー

2. 次に、以下の強調表示された行を挿入して例外を記録します。この例外は New Relic でスパン イベントとして表示され、スパンのステータスを ERRORに設定します。

   @app.route("/fibonacci")
   @trace.get_tracer("opentelemetry.instrumentation.custom").start_as_current_span("/fibonacci")
   def fibonacci():
       args = request.args
       x = int(args.get("n"))
       error_message = "n must be 1 <= n <= 90."
       trace.get_current_span().set_attribute("fibonacci.n", x)
   
       try:
           assert 1 <= x <= 90
           array = [0, 1]
           for n in range(2, x + 1):
               array.append(array[n - 1] + array[n - 2])
   
           trace.get_current_span().set_attribute("fibonacci.result", array[x])
           return jsonify(n=x, result=array[x])
   
       except AssertionError:
           trace.get_current_span().record_exception(exception=Exception, attributes={"exception.type": "AssertionError", "exception.message": error_message})
           trace.get_current_span().set_status(Status(StatusCode.ERROR, error_message))
           return jsonify({"message": error_message})
   
   app.run(host='0.0.0.0', port=8080)

   コピー

カスタム メトリック インストルメンテーション: カスタム メトリック カウンターを追加します。

メトリックは、個々の測定値を集計に結合し、システム負荷の関数として一定のデータを生成するため、非常に役立つテレメトリ データ タイプです。このデータをスパンと組み合わせて使用すると、傾向を特定し、アプリケーションのランタイム テレメトリを提供できます。また、メトリクスが表す測定値の下位区分を説明するのに役立つ属性でメトリクスに注釈を付けることもできます。

OpenTelemetry メトリクス API は、メトリクス SDK によって集計され、アウト オブ プロセスでエクスポートされる測定値を記録する多数の計測器を定義します。器具には次の 2 種類があります。

• 同期: これらの計測器は、発生時に測定値を記録します。
• 非同期: これらの計測器はコールバックを登録します。これはコレクションごとに 1 回だけ呼び出され、関連付けられたコンテキストはありません。

1. ステップEで、カウンターを作成する以下の強調表示された行を追加しました。

   ###########
   # Metrics #
   ###########
   from opentelemetry import metrics
   from opentelemetry.sdk.metrics import MeterProvider
   from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
   from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
   
   # Initialize metering and an exporter that can send data to an OTLP endpoint
   # SELECT count(`http.server.active_requests`) FROM Metric FACET `service.name` TIMESERIES
   metrics.set_meter_provider(MeterProvider(resource=Resource.create(OTEL_RESOURCE_ATTRIBUTES), metric_readers=[PeriodicExportingMetricReader(OTLPMetricExporter())]))
   metrics.get_meter_provider()
   fib_counter = metrics.get_meter("opentelemetry.instrumentation.custom").create_counter("fibonacci.invocations", unit="1", description="Measures the number of times the fibonacci method is invoked.")

   コピー

2. 次に、作成したカウンターを使用して測定するために、以下の強調表示された行を追加します。

• この関数が正常に実行された回数

• 実行に失敗した回数

  アプリを再起動するたびにカウンターが 0 にリセットされることに注意してください。

  @app.route("/fibonacci")
  @trace.get_tracer("opentelemetry.instrumentation.custom").start_as_current_span("/fibonacci")
  def fibonacci():
      args = request.args
      x = int(args.get("n"))
      error_message = "n must be 1 <= n <= 90."
      trace.get_current_span().set_attribute("fibonacci.n", x)
  
      try:
          assert 1 <= x <= 90
          array = [0, 1]
          for n in range(2, x + 1):
              array.append(array[n - 1] + array[n - 2])
  
          trace.get_current_span().set_attribute("fibonacci.result", array[x])
          fib_counter.add(1, {"fibonacci.valid.n": "true"})
          return jsonify(n=x, result=array[x])
  
      except AssertionError:
          trace.get_current_span().record_exception(exception=Exception, attributes={"exception.type": "AssertionError", "exception.message": error_message})
          trace.get_current_span().set_status(Status(StatusCode.ERROR, error_message))
          fib_counter.add(1, {"fibonacci.valid.n": "false"})
          return jsonify({"message": error_message})
  
  app.run(host='0.0.0.0', port=8080)

  コピー

カスタムログ計測

OpenTelemetry Python のログ信号のステータスは、現在 実験段階です。

app.pyで、以下の強調表示された行を次の行に追加します。

• 入力値と出力値の INFO レベルのログを記録します。

• 入力値が有効範囲外の場合、 ERROR レベルのログを記録します。

  @app.route("/fibonacci")
  @trace.get_tracer("opentelemetry.instrumentation.custom").start_as_current_span("/fibonacci")
  def fibonacci():
      args = request.args
      x = int(args.get("n"))
      error_message = "n must be 1 <= n <= 90."
      trace.get_current_span().set_attribute("fibonacci.n", x)
  
      try:
          assert 1 <= x <= 90
          array = [0, 1]
          for n in range(2, x + 1):
              array.append(array[n - 1] + array[n - 2])
  
          trace.get_current_span().set_attribute("fibonacci.result", array[x])
          fib_counter.add(1, {"fibonacci.valid.n": "true"})
          logging.info("Compute fibonacci(" + str(x) + ") = " + str(array[x]))
          return jsonify(n=x, result=array[x])
  
      except AssertionError:
          trace.get_current_span().record_exception(exception=Exception, attributes={"exception.type": "AssertionError", "exception.message": error_message})
          trace.get_current_span().set_status(Status(StatusCode.ERROR, error_message))
          fib_counter.add(1, {"fibonacci.valid.n": "false"})
          logging.error("Failed to compute fibonacci(" + str(x) + ")")
          return jsonify({"message": error_message})
  
  app.run(host='0.0.0.0', port=8080)

  コピー

アプリを実行してトラフィックを生成する

New Relic にデータを送信する準備ができました!

1. ターミナルで、 getting-started-guides/python/Uninstrumented ディレクトリにいることを確認し、アプリケーションを実行します。

   • マックOS：

     python3 app.py

     コピー

   • パワーシェル：

     python app.py

     コピー

2. getting-started-guides/python/Uninstrumented ディレクトリで新しいターミナル タブを開き、ロード ジェネレーターを実行して、アプリケーションへのトラフィックを生成します。

   • マックOS：

     ./load-generator.sh

     コピー

   • パワーシェル：

     .\load-generator.ps1

     コピー

   ヒント

   または、ブラウザの次の URL でエンドポイントにアクセスできます: http://localhost:8080/fibonacci?n=INSERT_A_VALUE 。INSERT_A_VALUEを 1 から 90 の値に置き換えます。エラーを生成するには、有効範囲外の整数を挿入します。

3. New Relic にデータを送信したので、UI でデータを表示する手順を参照してください。