베타 Observability 스팬 엔드포인트

베타 Observability 스팬 엔드포인트 (Beta Observability Spans Endpoints)

(beta) Observability API - spans입니다. 스팬(span)을 검색·집계하고, 스팬 평가를 검색·집계하며, 스팬 필드 정의와 옵션을 조회하는 엔드포인트예요.

출처: 문서

본문

추적(tracing)의 기본 단위인 스팬 데이터를 다루는 베타 API예요. 스팬을 조건으로 검색하고, 지표(metric) 기준으로 집계하며, 스팬에 붙은 평가(evaluation) 결과까지 확인할 수 있답니다.

POST /v1/observability/spans/search — Search spans (스팬 검색)

스팬을 검색합니다.

요청 본문:

  • search_expression#string|null — 검색 표현식.

응답 필드 (200 Successful Response):

  • spans#FeedResultGetSpan (필수)

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.observability.spans.searchSpans({
    spansRequest: {},
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.observability.spans.search_spans(page_size=50)

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/observability/spans/search \
 -X POST \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{}'

응답 예시 (200):

{
  "spans": {}
}

POST /v1/observability/spans/aggregate — Aggregate spans (스팬 집계)

스팬을 집계합니다.

요청 본문:

  • metric#MetricDefinition (필수) — 집계 지표(측정값, 집계 방식 등).
  • search_expression#string|null
  • dimensions#array<string> — 그룹화할 차원.
  • order_by#array<OrderByClause>|null
  • time_dimension#TimeDimension|null
  • limit#integer — 기본값 1000.
  • from#date-time|null
  • to#date-time|null

응답 필드 (200 Successful Response):

  • data#array<AggregationRow> (필수)
  • meta#AggregationMeta (필수)

curl:

curl https://api.mistral.ai/v1/observability/spans/aggregate \
 -X POST \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{
  "metric": {
    "aggregation": "count",
    "measure": "ipsum eiusmod"
  }
}'

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.observability.spans.aggregate({
    aggregationRequest: {
      metric: {
        measure: "<value>",
        aggregation: "p99",
      },
    },
  });

  console.log(result);
}

run();

응답 예시 (200):

{
  "data": [
    {
      "metric_name": "ipsum eiusmod"
    }
  ],
  "meta": {
    "from_timestamp": "2025-12-17T10:25:07.818693Z",
    "to_timestamp": "2025-12-17T10:25:07.818693Z"
  }
}

POST /v1/observability/spans/evaluations/aggregate — Aggregate span evaluations (스팬 평가 집계)

스팬 평가 결과를 집계합니다.

요청 본문: spans/aggregate와 동일한 aggregationRequest 구조입니다 (from, to, dimensions, limit, metric, order_by, search_expression, time_dimension).

응답 필드 (200 Successful Response):

  • data#array<AggregationRow> (필수)
  • meta#AggregationMeta (필수)

curl:

curl https://api.mistral.ai/v1/observability/spans/evaluations/aggregate \
 -X POST \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{
  "metric": {
    "aggregation": "count",
    "measure": "ipsum eiusmod"
  }
}'

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.observability.spans.aggregateSpanEvaluations({
    aggregationRequest: {
      metric: {
        measure: "<value>",
        aggregation: "max",
      },
    },
  });

  console.log(result);
}

run();

POST /v1/observability/spans/evaluations/search — Search span evaluations (스팬 평가 검색)

스팬 평가를 검색합니다.

요청 본문:

  • search_expression#string|null

응답 필드 (200 Successful Response):

  • span_evaluations#FeedResultGetSpanEvaluation (필수)

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.observability.spans.searchSpanEvaluations({
    spanEvaluationsRequest: {},
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.observability.spans.search_span_evaluations(page_size=50)

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/observability/spans/evaluations/search \
 -X POST \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{}'

POST /v1/observability/spans/evaluations/search/latest — Search latest span evaluations (최신 스팬 평가 검색)

가장 최신 스팬 평가를 검색합니다.

요청 본문:

  • search_expression#string|null

응답 필드 (200 Successful Response):

  • span_evaluations#FeedResultGetSpanEvaluation (필수)

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.observability.spans.searchLatestSpanEvaluations({
    spanEvaluationsRequest: {},
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.observability.spans.search_latest_span_evaluations(page_size=50)

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/observability/spans/evaluations/search/latest \
 -X POST \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{}'

GET /v1/observability/spans/fields — Get span field definitions (스팬 필드 정의)

스팬 필드 정의를 가져옵니다.

응답 필드 (200 Successful Response):

  • field_definitions#array<OtelFieldDefinition> (필수)

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.observability.spans.listSpanFields();

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.observability.spans.list_span_fields()

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/observability/spans/fields \
 -X GET \
 -H 'Authorization: Bearer ***'

응답 예시 (200):

{
  "field_definitions": [
    {
      "label": "approved",
      "name": "My resource",
      "supported_aggregations": [
        "count"
      ],
      "supported_operators": [
        "eq"
      ],
      "type": "ENUM"
    }
  ]
}

GET /v1/observability/spans/evaluations/fields — Get span evaluation field definitions (스팬 평가 필드 정의)

스팬 평가 필드 정의를 가져옵니다.

응답 필드 (200 Successful Response):

  • field_definitions#array<OtelFieldDefinition> (필수)

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.observability.spans.listSpanEvalFields();

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.observability.spans.list_span_eval_fields()

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/observability/spans/evaluations/fields \
 -X GET \
 -H 'Authorization: Bearer ***'

GET /v1/observability/spans/fields/{field_name}/options — Get options for a span field (스팬 필드 옵션)

특정 스팬 필드에서 사용 가능한 옵션 값을 가져옵니다.

경로/쿼리 파라미터:

  • field_name#string (필수)
  • from#date-time|null
  • to#date-time|null

응답 필드 (200 Successful Response):

  • options#array<string>|null (필수)

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.observability.spans.fetchSpanFieldOptions({
    fieldName: "<value>",
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.observability.spans.fetch_span_field_options(field_name="<value>")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/observability/spans/fields/{field_name}/options \
 -X GET \
 -H 'Authorization: Bearer ***'

응답 예시 (200):

{
  "options": null
}

GET /v1/observability/spans/evaluations/fields/{field_name}/options — Get options for a span evaluation field (스팬 평가 필드 옵션)

특정 스팬 평가 필드의 옵션 값을 가져옵니다.

경로/쿼리 파라미터:

  • field_name#string (필수)
  • from#date-time|null
  • to#date-time|null

응답 필드 (200 Successful Response):

  • options#array<string>|null (필수)

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.observability.spans.fetchSpanEvalFieldOptions({
    fieldName: "<value>",
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.observability.spans.fetch_span_eval_field_options(field_name="<value>")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/observability/spans/evaluations/fields/{field_name}/options \
 -X GET \
 -H 'Authorization: Bearer ***'

더 알아보기 (Learn more)