veadk-python 0.2.5__py3-none-any.whl → 0.2.7__py3-none-any.whl

veadk/tracing/telemetry/exporters/apmplus_exporter.py

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from dataclasses import dataclass
 from typing import Any
 
 from google.adk.models.llm_request import LlmRequest
@@ -28,13 +29,100 @@ from opentelemetry.sdk.trace.export import BatchSpanProcessor
 from pydantic import BaseModel, Field
 from typing_extensions import override
 
-from veadk.config import getenv
+from veadk.config import settings
 from veadk.tracing.telemetry.exporters.base_exporter import BaseExporter
 from veadk.utils.logger import get_logger
 
 logger = get_logger(__name__)
 
 
+_GEN_AI_CLIENT_OPERATION_DURATION_BUCKETS = [
+    0.01,
+    0.02,
+    0.04,
+    0.08,
+    0.16,
+    0.32,
+    0.64,
+    1.28,
+    2.56,
+    5.12,
+    10.24,
+    20.48,
+    40.96,
+    81.92,
+]
+
+_GEN_AI_SERVER_TIME_PER_OUTPUT_TOKEN_BUCKETS = [
+    0.01,
+    0.025,
+    0.05,
+    0.075,
+    0.1,
+    0.15,
+    0.2,
+    0.3,
+    0.4,
+    0.5,
+    0.75,
+    1.0,
+    2.5,
+]
+
+_GEN_AI_SERVER_TIME_TO_FIRST_TOKEN_BUCKETS = [
+    0.001,
+    0.005,
+    0.01,
+    0.02,
+    0.04,
+    0.06,
+    0.08,
+    0.1,
+    0.25,
+    0.5,
+    0.75,
+    1.0,
+    2.5,
+    5.0,
+    7.5,
+    10.0,
+]
+
+_GEN_AI_CLIENT_TOKEN_USAGE_BUCKETS = [
+    1,
+    4,
+    16,
+    64,
+    256,
+    1024,
+    4096,
+    16384,
+    65536,
+    262144,
+    1048576,
+    4194304,
+    16777216,
+    67108864,
+]
+
+
+@dataclass
+class Meters:
+    LLM_CHAT_COUNT = "gen_ai.chat.count"
+    LLM_TOKEN_USAGE = "gen_ai.client.token.usage"
+    LLM_OPERATION_DURATION = "gen_ai.client.operation.duration"
+    LLM_COMPLETIONS_EXCEPTIONS = "gen_ai.chat_completions.exceptions"
+    LLM_STREAMING_TIME_TO_FIRST_TOKEN = (
+        "gen_ai.chat_completions.streaming_time_to_first_token"
+    )
+    LLM_STREAMING_TIME_TO_GENERATE = (
+        "gen_ai.chat_completions.streaming_time_to_generate"
+    )
+    LLM_STREAMING_TIME_PER_OUTPUT_TOKEN = (
+        "gen_ai.chat_completions.streaming_time_per_output_token"
+    )
+
+
 class MeterUploader:
     def __init__(
         self, name: str, endpoint: str, headers: dict, resource_attributes: dict
@@ -65,14 +153,44 @@ class MeterUploader:
 
         # create meter attributes
         self.llm_invoke_counter = self.meter.create_counter(
-            name="gen_ai.chat.count",
+            name=Meters.LLM_CHAT_COUNT,
             description="Number of LLM invocations",
             unit="count",
         )
         self.token_usage = self.meter.create_histogram(
-            name="gen_ai.client.token.usage",
+            name=Meters.LLM_TOKEN_USAGE,
             description="Token consumption of LLM invocations",
             unit="count",
+            explicit_bucket_boundaries_advisory=_GEN_AI_CLIENT_TOKEN_USAGE_BUCKETS,
+        )
+        self.duration_histogram = self.meter.create_histogram(
+            name=Meters.LLM_OPERATION_DURATION,
+            unit="s",
+            description="GenAI operation duration",
+            explicit_bucket_boundaries_advisory=_GEN_AI_CLIENT_OPERATION_DURATION_BUCKETS,
+        )
+        self.chat_exception_counter = self.meter.create_counter(
+            name=Meters.LLM_COMPLETIONS_EXCEPTIONS,
+            unit="time",
+            description="Number of exceptions occurred during chat completions",
+        )
+        self.streaming_time_to_first_token = self.meter.create_histogram(
+            name=Meters.LLM_STREAMING_TIME_TO_FIRST_TOKEN,
+            unit="s",
+            description="Time to first token in streaming chat completions",
+            explicit_bucket_boundaries_advisory=_GEN_AI_SERVER_TIME_TO_FIRST_TOKEN_BUCKETS,
+        )
+        self.streaming_time_to_generate = self.meter.create_histogram(
+            name=Meters.LLM_STREAMING_TIME_TO_GENERATE,
+            unit="s",
+            description="Time between first token and completion in streaming chat completions",
+            explicit_bucket_boundaries_advisory=_GEN_AI_CLIENT_OPERATION_DURATION_BUCKETS,
+        )
+        self.streaming_time_per_output_token = self.meter.create_histogram(
+            name=Meters.LLM_STREAMING_TIME_PER_OUTPUT_TOKEN,
+            unit="s",
+            description="Time per output token in streaming chat completions",
+            explicit_bucket_boundaries_advisory=_GEN_AI_SERVER_TIME_PER_OUTPUT_TOKEN_BUCKETS,
         )
 
     def record(self, llm_request: LlmRequest, llm_response: LlmResponse) -> None:
@@ -99,22 +217,50 @@ class MeterUploader:
                 token_attributes = {**attributes, "gen_ai_token_type": "output"}
                 self.token_usage.record(output_token, attributes=token_attributes)
 
+            # TODO: Get llm duration
+            # duration = 5.0
+            # if self.duration_histogram:
+            #     self.duration_histogram.record(duration, attributes=attributes)
+
+            # Get model request error
+            if llm_response.error_code and self.chat_exception_counter:
+                exception_attributes = {
+                    **attributes,
+                    "error_type": llm_response.error_message,
+                }
+                self.chat_exception_counter.add(1, exception_attributes)
+
+            # TODO: Get streaming time to first token
+            # time_to_frist_token = 0.1
+            # if self.streaming_time_to_first_token:
+            #     self.streaming_time_to_first_token.record(
+            #         time_to_frist_token, attributes=attributes
+            #     )
+
+            # TODO: Get streaming time to generate
+            # time_to_generate = 1.0
+            # if self.streaming_time_to_generate:
+            #     self.streaming_time_to_generate.record(
+            #         time_to_generate, attributes=attributes
+            #     )
+
+            # TODO: Get streaming time per output token
+            # time_per_output_token = 0.01
+            # if self.streaming_time_per_output_token:
+            #     self.streaming_time_per_output_token.record(
+            #         time_per_output_token, attributes=attributes
+            #     )
+
 
 class APMPlusExporterConfig(BaseModel):
     endpoint: str = Field(
-        default_factory=lambda: getenv(
-            "OBSERVABILITY_OPENTELEMETRY_APMPLUS_ENDPOINT",
-            "http://apmplus-cn-beijing.volces.com:4317",
-        ),
+        default_factory=lambda: settings.apmplus_config.otel_exporter_endpoint,
     )
     app_key: str = Field(
-        default_factory=lambda: getenv("OBSERVABILITY_OPENTELEMETRY_APMPLUS_API_KEY"),
+        default_factory=lambda: settings.apmplus_config.otel_exporter_api_key,
     )
     service_name: str = Field(
-        default_factory=lambda: getenv(
-            "OBSERVABILITY_OPENTELEMETRY_APMPLUS_SERVICE_NAME",
-            "veadk_tracing_service",
-        ),
+        default_factory=lambda: settings.apmplus_config.otel_exporter_service_name,
         description="Service name shown in APMPlus frontend.",
     )
 

veadk/tracing/telemetry/exporters/cozeloop_exporter.py

@@ -19,7 +19,7 @@ from opentelemetry.sdk.trace.export import BatchSpanProcessor
 from pydantic import BaseModel, Field
 from typing_extensions import override
 
-from veadk.config import getenv
+from veadk.config import settings
 from veadk.tracing.telemetry.exporters.base_exporter import BaseExporter
 from veadk.utils.logger import get_logger
 
@@ -28,18 +28,13 @@ logger = get_logger(__name__)
 
 class CozeloopExporterConfig(BaseModel):
     endpoint: str = Field(
-        default_factory=lambda: getenv(
-            "OBSERVABILITY_OPENTELEMETRY_COZELOOP_ENDPOINT",
-            "https://api.coze.cn/v1/loop/opentelemetry/v1/traces",
-        ),
+        default_factory=lambda: settings.cozeloop_config.otel_exporter_endpoint,
     )
     space_id: str = Field(
-        default_factory=lambda: getenv(
-            "OBSERVABILITY_OPENTELEMETRY_COZELOOP_SERVICE_NAME"
-        ),
+        default_factory=lambda: settings.cozeloop_config.otel_exporter_space_id,
     )
     token: str = Field(
-        default_factory=lambda: getenv("OBSERVABILITY_OPENTELEMETRY_COZELOOP_API_KEY"),
+        default_factory=lambda: settings.cozeloop_config.otel_exporter_api_key,
     )
 
 

veadk/tracing/telemetry/exporters/tls_exporter.py

@@ -19,7 +19,7 @@ from opentelemetry.sdk.trace.export import BatchSpanProcessor
 from pydantic import BaseModel, Field
 from typing_extensions import override
 
-from veadk.config import getenv
+from veadk.config import getenv, settings
 from veadk.tracing.telemetry.exporters.base_exporter import BaseExporter
 from veadk.utils.logger import get_logger
 
@@ -28,19 +28,13 @@ logger = get_logger(__name__)
 
 class TLSExporterConfig(BaseModel):
     endpoint: str = Field(
-        default_factory=lambda: getenv(
-            "OBSERVABILITY_OPENTELEMETRY_TLS_ENDPOINT",
-            "https://tls-cn-beijing.volces.com:4318/v1/traces",
-        ),
+        default_factory=lambda: settings.tls_config.otel_exporter_endpoint,
     )
     region: str = Field(
-        default_factory=lambda: getenv(
-            "OBSERVABILITY_OPENTELEMETRY_TLS_REGION",
-            "cn-beijing",
-        ),
+        default_factory=lambda: settings.tls_config.otel_exporter_region,
     )
     topic_id: str = Field(
-        default_factory=lambda: getenv("OBSERVABILITY_OPENTELEMETRY_TLS_SERVICE_NAME"),
+        default_factory=lambda: settings.tls_config.otel_exporter_topic_id,
     )
     access_key: str = Field(default_factory=lambda: getenv("VOLCENGINE_ACCESS_KEY"))
     secret_key: str = Field(default_factory=lambda: getenv("VOLCENGINE_SECRET_KEY"))

veadk/tracing/telemetry/opentelemetry_tracer.py

@@ -30,9 +30,9 @@ from typing_extensions import override
 from veadk.tracing.base_tracer import BaseTracer
 from veadk.tracing.telemetry.exporters.apmplus_exporter import APMPlusExporter
 from veadk.tracing.telemetry.exporters.base_exporter import BaseExporter
-from veadk.tracing.telemetry.exporters.inmemory_exporter import InMemoryExporter
 from veadk.tracing.telemetry.exporters.inmemory_exporter import (
     _INMEMORY_EXPORTER_INSTANCE,
+    InMemoryExporter,
 )
 from veadk.utils.logger import get_logger
 from veadk.utils.patches import patch_google_adk_telemetry
@@ -58,6 +58,8 @@ class OpentelemetryTracer(BaseModel, BaseTracer):
         description="The exporters to export spans.",
     )
 
+    # Forbid InMemoryExporter in exporters list
+    # cause we need to set custom in-memory span processor by VeADK
     @field_validator("exporters")
     @classmethod
     def forbid_inmemory_exporter(cls, v: list[BaseExporter]) -> list[BaseExporter]:
@@ -67,14 +69,18 @@ class OpentelemetryTracer(BaseModel, BaseTracer):
         return v
 
     def model_post_init(self, context: Any) -> None:
+        # Replace Google ADK tracing funcs
+        # `trace_call_llm` and `trace_tool_call`
         patch_google_adk_telemetry()
-        self._init_global_tracer_provider()
-
-    #  GoogleADKInstrumentor().instrument()
 
-    def _init_global_tracer_provider(self) -> None:
+        # We save internal processors for tracing data dump
         self._processors = []
 
+        # Initialize global tracer provider to avoid VeFaaS global tracer
+        # provider conflicts
+        self._init_global_tracer_provider()
+
+    def _init_global_tracer_provider(self) -> None:
         # set provider anyway, then get global provider
         trace_api.set_tracer_provider(trace_sdk.TracerProvider())
         global_tracer_provider: TracerProvider = trace_api.get_tracer_provider()  # type: ignore

veadk/tracing/telemetry/telemetry.py

@@ -92,10 +92,16 @@ def _set_agent_input_attribute(
                     "gen_ai.user.message",
                     {
                         f"parts.{idx}.type": "image_url",
-                        f"parts.{idx}.image_url.name": part.inline_data.display_name.split(
-                            "/"
-                        )[-1],
-                        f"parts.{idx}.image_url.url": part.inline_data.display_name,
+                        f"parts.{idx}.image_url.name": (
+                            part.inline_data.display_name.split("/")[-1]
+                            if part.inline_data.display_name
+                            else "<unknown_image_name>"
+                        ),
+                        f"parts.{idx}.image_url.url": (
+                            part.inline_data.display_name
+                            if part.inline_data.display_name
+                            else "<unknown_image_url>"
+                        ),
                     },
                 )
 
@@ -174,7 +180,10 @@ def set_common_attributes_on_tool_span(current_span: _Span) -> None:
         if span.context.span_id == parent_span_id:
             common_attributes = ATTRIBUTES.get("common", {})
             for attr_name in common_attributes.keys():
-                current_span.set_attribute(attr_name, span.attributes[attr_name])
+                if hasattr(span.attributes, attr_name):
+                    current_span.set_attribute(attr_name, span.attributes[attr_name])
+                else:
+                    logger.error(f"Parent span does not have attribute {attr_name}")
 
 
 def trace_send_data(): ...
@@ -221,6 +230,15 @@ def trace_call_llm(
         model_name=invocation_context.agent.model_name
         if isinstance(invocation_context.agent, Agent)
         else "",
+        call_type=(
+            span.context.trace_state.get("call_type", "")
+            if (
+                hasattr(span, "context")
+                and hasattr(span.context, "trace_state")
+                and hasattr(span.context.trace_state, "get")
+            )
+            else ""
+        ),
     )
 
     llm_attributes_mapping = ATTRIBUTES.get("llm", {})

veadk/utils/logger.py

@@ -16,7 +16,7 @@ import sys
 
 from loguru import logger
 
-from veadk.config import getenv
+from veadk.utils.misc import getenv
 
 
 def filter_log():

veadk/utils/misc.py

@@ -14,12 +14,14 @@
 
 import importlib.util
 import json
+import os
 import sys
 import time
 import types
 from typing import Any, Dict, List, MutableMapping, Tuple
 
 import requests
+from yaml import safe_load
 
 
 def read_file(file_path):
@@ -100,3 +102,49 @@ def safe_json_serialize(obj) -> str:
         )
     except (TypeError, OverflowError):
         return "<not serializable>"
+
+
+def getenv(
+    env_name: str, default_value: Any = "", allow_false_values: bool = False
+) -> str:
+    """
+    Get environment variable.
+
+    Args:
+        env_name (str): The name of the environment variable.
+        default_value (str): The default value of the environment variable.
+        allow_false_values (bool, optional): Whether to allow the environment variable to be None or false values. Defaults to False.
+
+    Returns:
+        str: The value of the environment variable.
+    """
+    value = os.getenv(env_name, default_value)
+
+    if allow_false_values:
+        return value
+
+    if value:
+        return value
+    else:
+        raise ValueError(
+            f"The environment variable `{env_name}` not exists. Please set this in your environment variable or config.yaml."
+        )
+
+
+def set_envs(config_yaml_path: str) -> tuple[dict, dict]:
+    with open(config_yaml_path, "r", encoding="utf-8") as yaml_file:
+        config_dict = safe_load(yaml_file)
+
+    flatten_config_dict = flatten_dict(config_dict)
+
+    veadk_environments = {}
+    for k, v in flatten_config_dict.items():
+        k = k.upper()
+
+        if k in os.environ:
+            veadk_environments[k] = os.environ[k]
+            continue
+        veadk_environments[k] = str(v)
+        os.environ[k] = str(v)
+
+    return config_dict, veadk_environments

veadk/utils/volcengine_sign.py

@@ -153,7 +153,10 @@ def request(method, date, query, header, ak, sk, action, body):
         params=request_param["query"],
         data=request_param["body"],
     )
-    return r.json()
+    try:
+        return r.json()
+    except Exception:
+        raise ValueError(f"Error occurred. Bad response: {r}")
 
 
 def ve_request(
@@ -166,6 +169,7 @@ def ve_request(
     region: str,
     host: str,
     content_type: str = "application/json",
+    header: dict = {},
 ):
     # response_body = request("Get", datetime.datetime.utcnow(), {}, {}, AK, SK, "ListUsers", None)
     # print(response_body)
@@ -192,7 +196,7 @@ def ve_request(
 
     try:
         response_body = request(
-            "POST", now, {}, {}, AK, SK, action, json.dumps(request_body)
+            "POST", now, {}, header, AK, SK, action, json.dumps(request_body)
         )
         return response_body
     except Exception as e:

veadk/version.py

@@ -12,4 +12,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-VERSION = "0.2.5"
+VERSION = "0.2.7"

{veadk_python-0.2.5.dist-info → veadk_python-0.2.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: veadk-python
-Version: 0.2.5
+Version: 0.2.7
 Summary: Volcengine agent development kit, integrations with Volcengine cloud services.
 Author-email: Yaozheng Fang <fangyozheng@gmail.com>, Guodong Li <cu.eric.lee@gmail.com>, Zhi Han <sliverydayday@gmail.com>, Meng Wang <mengwangwm@gmail.com>
 License:                                  Apache License
@@ -223,6 +223,7 @@ Requires-Dist: agent-pilot-sdk>=0.0.9
 Requires-Dist: fastmcp>=2.11.3
 Requires-Dist: cookiecutter>=2.6.0
 Requires-Dist: opensearch-py==2.8.0
+Requires-Dist: omegaconf>=2.3.0
 Provides-Extra: database
 Requires-Dist: redis>=6.2.0; extra == "database"
 Requires-Dist: pymysql>=1.1.1; extra == "database"