属性を定義してログする

このページでは、@weave.op デコレーターでトレースする関数の属性について説明します。Weave エージェント SDK でエージェントをインストルメントする場合は、代わりにエージェントスパン (Turn、LLM、Tool、SubAgent) に属性とイベントを設定してください。詳しくは、エージェントスパンに属性とイベントを設定するを参照してください。

Weave の属性を使用すると、トレースと評価にカスタムメタデータを付加できます。このメタデータには、環境名、モデルのバージョン、実験 ID、ユーザー ID などのコンテキスト情報を含めることができ、Weave データの整理、フィルター、分析に役立ちます。属性は、次のような単位でトレースをグループ化またはフィルターする場合に特に役立ちます。

デプロイメント
テナント
実験

Weave で属性を追加する方法は 2 つあります。

Call ごとの属性: weave.attributes() コンテキストマネージャーを使用して、特定の操作やコードブロックにメタデータを追加します。
グローバル属性: global_attributes フィールドを使用して、project 内のすべてのトレースと評価に適用される属性を初期化時に設定します。

トレースと評価でログされたすべての属性は UI で確認でき、データのフィルターやグループ化に使用できます。このガイドは、トレースと評価にカスタムメタデータを追加して情報を充実させたい Weave ユーザーを対象としています。個々の Call に属性を付加する方法、初期化時に project 全体のデフォルトを設定する方法、両者を組み合わせる方法、実行中に現在の属性セットを読み取る方法について説明します。

Call ごとの属性

weave.attributes() コンテキストマネージャーを使用すると、トレース対象の特定の操作にメタデータを追加できます。特定の関数の Call や評価 run に、コンテキスト情報をタグとして付与したい場合に使用します。

Call の開始後は call.attributes を変更できません。op を呼び出す前に、このコンテキストマネージャーを使用してメタデータを設定してください。

Python
TypeScript

import weave

weave.init("[TEAM-NAME]/[PROJECT-NAME]")

@weave.op
def my_function(name: str):
    return f"Hello, {name}!"

# 特定の Call に属性を追加する
with weave.attributes({'env': 'production', 'user_id': '12345'}):
    result = my_function("World")

import {init, op, withAttributes} from 'weave';

async function main() {
  await init('your-team/attribute-example');

  const myFunction = op(async function myFunction(name: string) {
    return `Hello, ${name}!`;
  });

  // 特定の Call に属性を追加する
  const result = await withAttributes(
    {env: 'production', user_id: '12345'},
    async () => myFunction('World')
  );

  console.log('Result:', result);
}

main().catch(console.error);

この関数は、コンテキストマネージャーのブロック (Python) またはコールバック関数 (TypeScript) 内でトレースされるすべての操作に属性を付与します。 weave.attributes() コンテキストはネストすることもできます。同じキーがある場合は、内側のコンテキストの値で外側の値が上書きされます。

Python
TypeScript

@weave.op
def process_data(data: str):
    return data.upper()

# 外側のコンテキスト
with weave.attributes({
    "env": "production",
    "version": "1.0.0",
    "region": "us-west-2"
}):
    process_data("hello")  # 3 つの属性すべてを持つ
    
    # 内側のコンテキストが 'version' を上書きする
    with weave.attributes({
        "version": "1.1.0",
        "experiment": "exp-456"
    }):
        process_data("world")  # env='production', version='1.1.0', region='us-west-2', experiment='exp-456' を持つ

import {init, op, withAttributes} from 'weave';

async function main() {
  await init('your-team/attribute-example');

  const processData = op(async function processData(data: string) {
    return data.toUpperCase();
  });
  
  // 外側のコンテキスト
  await withAttributes(
    {
      env: 'production',
      version: '1.0.0',
      region: 'us-west-2'
    },
    async () => {
      await processData('hello');  // 3 つの属性すべてを持つ
      
      // 内側のコンテキストが 'version' を上書きする
      await withAttributes(
        {
          version: '1.1.0',
          experiment: 'exp-456'
        },
        async () => {
          await processData('world');  // env='production', version='1.1.0', region='us-west-2', experiment='exp-456' を持つ
        }
      );
    }
  );
}

main().catch(console.error);

グローバル属性

Weave の初期化時にグローバル属性を設定すると、project 内のすべてのトレースと評価に自動的に適用されます。環境、デプロイメントのバージョン、チーム情報など、project 全体で共通のメタデータを伝播させたい場合に便利です。

Python
TypeScript

import weave

weave.init(
    "my-project",
    global_attributes={
        "env": "production",
        "app_version": "2.1.0",
        "region": "us-west-2",
        "team": "ml-platform"
    }
)

# global_attributes 辞書により、以降のすべての操作にこれらの属性が適用されます
@weave.op
def my_function():
    return "Hello"

my_function()  # すべてのグローバル属性が自動的に付与されます

# 評価にもグローバル属性が付与されます
evaluation = weave.Evaluation(dataset=examples, scorers=[scorer])
asyncio.run(evaluation.evaluate(model))  # すべてのグローバル属性が付与されます

import {init, op, withAttributes} from 'weave';

async function main() {
    await init('your-team/attribute-example', {
        globalAttributes: {
            env: 'production',
            app_version: '2.1.0',
            region: 'us-west-2',
            team: 'ml-platform'
        }
    });
    
    // globalAttributes オブジェクトにより、以降のすべての操作にこれらの属性が適用されます
    const myFunction = op(async function myFunction() {
        return 'Hello';
    });
    
    const result = await myFunction();  // すべてのグローバル属性が自動的に付与されます
    console.log('Result:', result);
}
main().catch(console.error);

グローバル属性と Call ごとの属性を組み合わせる

グローバル属性と Call ごとの属性は併用できます。キーが同じ場合は、Call ごとの属性がグローバル属性を上書きします。

Python
TypeScript

import weave

# グローバル属性を設定する
weave.init(
    "my-project",
    global_attributes={
        "env": "production",
        "app_version": "2.1.0"
    }
)

@weave.op
def process(data: str):
    return data

# この Call の属性: env='production', app_version='2.1.0'
process("test1")

# この Call の属性: env='staging', app_version='2.1.0', experiment='A'
with weave.attributes({'env': 'staging', 'experiment': 'A'}):
    process("test2")

import {init, op, withAttributes} from 'weave';

async function main() {
    // グローバル属性を設定する
    await init('your-team/attribute-example', {
    globalAttributes: {
        env: 'production',
        app_version: '2.1.0'
    }
    });

    const process = op(async function process(data: string) {
    return data;
    });

    // この Call の属性: env='production', app_version='2.1.0'
    await process('test1');

    // この Call の属性: env='staging', app_version='2.1.0', experiment='A'
    await withAttributes(
    {env: 'staging', experiment: 'A'},
    async () => process('test2')
    );
}
main().catch(console.error);

実行中に属性を取得する

実行時に、Call に適用されている属性を確認できます。これは、Weave がどのメタデータを付与しているかをデバッグしたい場合や、外側の呼び出し元が設定したコンテキスト情報に応じてコードを分岐させる必要がある場合に便利です。

Python
TypeScript

次の例では、Weave デコレーターで process_data 関数をログするよう設定し、ログする属性を指定したうえで、実行時にそれらの属性を返します。

import weave

weave.init("your-team/your-project")

@weave.op
def process_data(data: str):
    # op 内で現在の call を取得する
    call = weave.get_current_call()
    if call:
        print(f"Attributes: {call.attributes}")
    return data.upper()

# 属性を設定して関数を実行する
with weave.attributes({
    "env": "production",
    "version": "1.0.0",
    "region": "us-west-2"
}):
    process_data("hello")
    
    with weave.attributes({
        "version": "1.1.0",
        "experiment": "exp-456"
    }):
        process_data("world")

出力は次のとおりです。

Attributes: {'env': 'production', 'version': '1.0.0', 'region': 'us-west-2'}
Attributes: {'env': 'production', 'version': '1.1.0', 'region': 'us-west-2', 'experiment': 'exp-456'}

weave.get_current_call() は、@weave.op でデコレートされた関数内でのみ動作します。op の外では None を返します。

Weave TypeScript SDK では、client.getCurrentAttributes() を使用して現在の属性を取得できます。Weave Python SDK とは異なり、TypeScript では op 内に限らず、withAttributes() コンテキスト内であればどこからでも属性にアクセスできます。

import * as weave from 'weave';
import { withAttributes } from 'weave';

async function main() {
  const client = await weave.init('your-team/your-project');

  const processData = weave.op(async function processData(data: string) {
    // op 内でも属性にアクセスできる
    const attrs = client.getCurrentAttributes();
    console.log('Attributes inside op:', attrs);
    return data.toUpperCase();
  });

  // 属性を設定して関数を実行する
  await withAttributes(
    {
      env: 'production',
      version: '1.0.0',
      region: 'us-west-2'
    },
    async () => {
      // コンテキスト内のどこからでも属性を取得できる
      console.log('Current attributes:', client.getCurrentAttributes());
      await processData('hello');

      await withAttributes(
        {
          version: '1.1.0',
          experiment: 'exp-456'
        },
        async () => {
          console.log('Nested attributes:', client.getCurrentAttributes());
          await processData('world');
        }
      );
    }
  );
}

main().catch(console.error);

出力は次のとおりです。

Current attributes: { env: 'production', version: '1.0.0', region: 'us-west-2' }
Attributes inside op: { env: 'production', version: '1.0.0', region: 'us-west-2' }
Nested attributes: { env: 'production', version: '1.1.0', region: 'us-west-2', experiment: 'exp-456' }
Attributes inside op: { env: 'production', version: '1.1.0', region: 'us-west-2', experiment: 'exp-456' }

​Call ごとの属性

​グローバル属性

​グローバル属性と Call ごとの属性を組み合わせる

​実行中に属性を取得する

Call ごとの属性

グローバル属性

グローバル属性と Call ごとの属性を組み合わせる

実行中に属性を取得する