可观测性

错误捕获、事件追踪、指标与特性开关。

概览

基础路径: /v1/observability

Python 命名空间: infra

text

# Python
from infrai import infra

# TypeScript
import { InfraiClient } from "@infrai/sdk";
const client = new InfraiClient({ apiKey: process.env.INFRAI_API_KEY! });
// → client.observability

方法

observability.error.capture

POST /v1/observability/errors

捕获应用错误，可选标签。

Python

python

infra.error.capture(...)

TypeScript

typescript

client.observability.captureError(err): Promise<{ ok, error_id }>

参数

名称	类型	必填	说明
`message`	`string`	必填	可读的错误消息。
`code`	`string`	可选	可选的应用错误码。
`stack`	`string`	可选	可选的堆栈跟踪。
`tags`	`Record<string, string>`	可选	用于分组的键/值标签。

{ ok, error_id }

示例

一次性前置(每个范例都假定已完成):

bash

pip install infrai
# one-time auth (no secret needed): anonymous account + trial, writes ~/.infrai/credentials
python -c "from infrai import infra; infra.activate()"
# returning user instead: export INFRAI_API_KEY=ifr_pk_proj_...

python

from infrai import infra

res = infra.error.capture(message="payment webhook failed",
                          code="WEBHOOK_TIMEOUT", tags={"service": "billing"})
print("error_id:", res.get("error_id"))

observability.event.track

POST /v1/observability/events

追踪带属性的产品事件。

Python

python

infra.analytics.track(event=..., properties=...)

TypeScript

typescript

client.observability.track(ev: TrackEvent): Promise<{ ok }>

参数

名称	类型	必填	说明
`event`	`string`	必填	事件名称。
`properties`	`Record<string, unknown>`	可选	任意事件属性。
`distinct_id`	`string`	可选	操作用户的稳定 id。

{ ok: boolean }

示例

一次性前置(每个范例都假定已完成):

bash

pip install infrai
# one-time auth (no secret needed): anonymous account + trial, writes ~/.infrai/credentials
python -c "from infrai import infra; infra.activate()"
# returning user instead: export INFRAI_API_KEY=ifr_pk_proj_...

python

from infrai import infra

infra.analytics.track(event="checkout_completed",
                      properties={"plan": "pro", "amount_usd": 20})
print("tracked")

observability.metric.report

POST /v1/observability/metrics

上报一个或多个指标点。

Python

python

# see capability observability.metric.report

TypeScript

typescript

client.observability.metric(m: MetricPoint | MetricPoint[]): Promise<{ ok }>

参数

名称	类型	必填	说明
`name`	`string`	必填	指标名称。
`value`	`number`	必填	指标数值。
`tags`	`Record<string, string>`	可选	用于分组的键/值标签。

{ ok: boolean }

示例

一次性前置(每个范例都假定已完成):

bash

pip install infrai
# one-time auth (no secret needed): anonymous account + trial, writes ~/.infrai/credentials
python -c "from infrai import infra; infra.activate()"
# returning user instead: export INFRAI_API_KEY=ifr_pk_proj_...

python

from infrai import infra

infra.metric.report(name="queue.depth", value=42, tags={"queue": "emails"})
print("reported")

observability.flag.is_enabled

GET /v1/observability/flags/{key}

为当前上下文评估特性开关。

Python

python

infra.flag.is_enabled(key)

TypeScript

typescript

// see ROUTES["observability.flag.is_enabled"]

参数

名称	类型	必填	说明
`key`	`string`	必填	特性开关 key。

{ enabled: boolean }

示例

一次性前置(每个范例都假定已完成):

bash

pip install infrai
# one-time auth (no secret needed): anonymous account + trial, writes ~/.infrai/credentials
python -c "from infrai import infra; infra.activate()"
# returning user instead: export INFRAI_API_KEY=ifr_pk_proj_...

python

from infrai import infra

if infra.flag.is_enabled("new_checkout", user_id="u_123"):
    ...  # gated path
print("flag read")