python-etcd3-async 0.1.0__py3-none-any.whl

etcd3/trace_attributes.py

@@ -0,0 +1,434 @@
+"""etcd semantic attributes for OpenTelemetry tracing.
+
+This module defines standardized attributes for etcd operations in OpenTelemetry
+traces, following the OpenTelemetry semantic conventions:
+https://opentelemetry.io/docs/reference/specification/trace/semantic_conventions/
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict, Optional
+
+
+class EtcdOperationType(Enum):
+    """etcd operation types for tracing."""
+    
+    # KV operations
+    KV_GET = "kv.get"
+    KV_PUT = "kv.put"
+    KV_DELETE = "kv.delete"
+    KV_RANGE = "kv.range"
+    KV_TXN = "kv.transaction"
+    
+    # Lease operations
+    LEASE_GRANT = "lease.grant"
+    LEASE_REVOKE = "lease.revoke"
+    LEASE_KEEPALIVE = "lease.keepalive"
+    LEASE_TTL = "lease.ttl"
+    
+    # Lock operations
+    LOCK_ACQUIRE = "lock.acquire"
+    LOCK_RELEASE = "lock.release"
+    LOCK_REFRESH = "lock.refresh"
+    
+    # Watch operations
+    WATCH_CREATE = "watch.create"
+    WATCH_CANCEL = "watch.cancel"
+    
+    # Cluster operations
+    CLUSTER_MEMBER_ADD = "cluster.member.add"
+    CLUSTER_MEMBER_REMOVE = "cluster.member.remove"
+    CLUSTER_MEMBER_UPDATE = "cluster.member.update"
+    CLUSTER_MEMBER_LIST = "cluster.member.list"
+    
+    # Maintenance operations
+    MAINTENANCE_STATUS = "maintenance.status"
+    MAINTENANCE_COMPACT = "maintenance.compact"
+    MAINTENANCE_DEFRAG = "maintenance.defragment"
+
+
+@dataclass(frozen=True)
+class TraceAttributes:
+    """Standard attribute names for etcd OpenTelemetry traces.
+    
+    These attributes follow OpenTelemetry semantic conventions where applicable
+    and define etcd-specific attributes for comprehensive observability.
+    """
+    
+    # === OpenTelemetry Standard Database Attributes ===
+    DB_SYSTEM = "db.system"
+    """Database system: always 'etcd' for this client."""
+    
+    DB_OPERATION = "db.operation"
+    """Database operation name (e.g., 'kv.get', 'lease.grant')."""
+    
+    DB_STATEMENT = "db.statement"
+    """Database statement (for complex queries, optional)."""
+    
+    # === etcd Key-Value Attributes ===
+    ETCD_KEY = "etcd.key"
+    """The key being operated on."""
+    
+    ETCD_RANGE_END = "etcd.range_end"
+    """End of the key range for range operations."""
+    
+    ETCD_LIMIT = "etcd.limit"
+    """Maximum number of keys to return."""
+    
+    ETCD_REVISION = "etcd.revision"
+    """Current revision of the operation result."""
+    
+    ETCD_PREV_REVISION = "etcd.prev_revision"
+    """Previous revision (for compare operations)."""
+    
+    ETCD_COUNT = "etcd.count"
+    """Number of keys returned or affected."""
+    
+    ETCD_DELETED = "etcd.deleted"
+    """Number of keys deleted."""
+    
+    # === etcd Cluster Attributes ===
+    ETCD_ENDPOINT = "etcd.endpoint"
+    """The etcd endpoint being accessed."""
+    
+    ETCD_CLUSTER_ID = "etcd.cluster_id"
+    """Cluster ID from response header."""
+    
+    ETCD_MEMBER_ID = "etcd.member_id"
+    """Member ID from response header."""
+    
+    ETCD_RAFT_TERM = "etcd.raft_term"
+    """Raft term from response header."""
+    
+    # === etcd Lease Attributes ===
+    ETCD_LEASE_ID = "etcd.lease.id"
+    """Lease ID."""
+    
+    ETCD_LEASE_TTL = "etcd.lease.ttl"
+    """Lease TTL in seconds."""
+    
+    ETCD_LEASE_REMAINING_TTL = "etcd.lease.remaining_ttl"
+    """Remaining TTL for the lease."""
+    
+    # === etcd Lock Attributes ===
+    ETCD_LOCK_NAME = "etcd.lock.name"
+    """Lock name (key path)."""
+    
+    ETCD_LOCK_UUID = "etcd.lock.uuid"
+    """Lock UUID (first 8 bytes)."""
+    
+    ETCD_LOCK_ACQUIRED = "etcd.lock.acquired"
+    """Whether the lock was successfully acquired."""
+    
+    # === etcd Transaction Attributes ===
+    ETCD_TXN_COMPARE_COUNT = "etcd.txn.compare_count"
+    """Number of compare conditions."""
+    
+    ETCD_TXN_SUCCESS_COUNT = "etcd.txn.success_count"
+    """Number of success operations."""
+    
+    ETCD_TXN_FAILURE_COUNT = "etcd.txn.failure_count"
+    """Number of failure operations."""
+    
+    ETCD_TXN_SUCCEEDED = "etcd.txn.succeeded"
+    """Whether the transaction succeeded."""
+    
+    # === etcd Batch Attributes ===
+    ETCD_BATCH_SIZE = "etcd.batch.size"
+    """Number of operations in the batch."""
+    
+    ETCD_BATCH_ATOMIC = "etcd.batch.atomic"
+    """Whether the batch is atomic."""
+    
+    # === etcd Error Attributes ===
+    ETCD_ERROR_CODE = "etcd.error_code"
+    """Error code if operation failed."""
+    
+    ETCD_ERROR_MESSAGE = "etcd.error_message"
+    """Error message if operation failed."""
+    
+    # === Retry Attributes ===
+    ETCD_RETRY_COUNT = "etcd.retry.count"
+    """Number of retries for this operation."""
+    
+    ETCD_RETRY_ENDPOINT = "etcd.retry.endpoint"
+    """Endpoint used after retry."""
+
+
+def _safe_decode(value: Optional[bytes], max_length: int = 256) -> Optional[str]:
+    """Safely decode bytes to string for attribute values.
+    
+    Args:
+        value: Bytes value to decode
+        max_length: Maximum length for the decoded string
+        
+    Returns:
+        Decoded string or None if input is None
+    """
+    if value is None:
+        return None
+    
+    try:
+        decoded = value.decode('utf-8', errors='replace')
+        if len(decoded) > max_length:
+            decoded = decoded[:max_length] + "..."
+        return decoded
+    except Exception:
+        return repr(value)
+
+
+def build_kv_attributes(
+    operation: str,
+    key: Optional[bytes] = None,
+    range_end: Optional[bytes] = None,
+    limit: Optional[int] = None,
+    **kwargs
+) -> Dict[str, Any]:
+    """Build trace attributes for KV operations.
+    
+    Args:
+        operation: Operation type (e.g., 'kv.get', 'kv.put')
+        key: The key being operated on
+        range_end: End of key range for range operations
+        limit: Maximum number of keys to return
+        **kwargs: Additional attributes
+        
+    Returns:
+        Dictionary of trace attributes
+    """
+    attrs = {
+        TraceAttributes.DB_SYSTEM: "etcd",
+        TraceAttributes.DB_OPERATION: operation,
+    }
+    
+    if key is not None:
+        attrs[TraceAttributes.ETCD_KEY] = _safe_decode(key)
+    
+    if range_end is not None:
+        attrs[TraceAttributes.ETCD_RANGE_END] = _safe_decode(range_end)
+    
+    if limit is not None:
+        attrs[TraceAttributes.ETCD_LIMIT] = limit
+    
+    attrs.update(kwargs)
+    return attrs
+
+
+def build_response_attributes(
+    header=None,
+    count: Optional[int] = None,
+    deleted: Optional[int] = None,
+    **kwargs
+) -> Dict[str, Any]:
+    """Build trace attributes from etcd response.
+    
+    Args:
+        header: Response header from etcd
+        count: Number of keys returned/affected
+        deleted: Number of keys deleted
+        **kwargs: Additional attributes
+        
+    Returns:
+        Dictionary of trace attributes
+    """
+    attrs = {}
+    
+    if header:
+        attrs[TraceAttributes.ETCD_REVISION] = header.revision
+        attrs[TraceAttributes.ETCD_CLUSTER_ID] = header.cluster_id
+        attrs[TraceAttributes.ETCD_MEMBER_ID] = header.member_id
+        attrs[TraceAttributes.ETCD_RAFT_TERM] = header.raft_term
+    
+    if count is not None:
+        attrs[TraceAttributes.ETCD_COUNT] = count
+    
+    if deleted is not None:
+        attrs[TraceAttributes.ETCD_DELETED] = deleted
+    
+    attrs.update(kwargs)
+    return attrs
+
+
+def build_lease_attributes(
+    lease_id: Optional[int] = None,
+    ttl: Optional[int] = None,
+    remaining_ttl: Optional[int] = None,
+    **kwargs
+) -> Dict[str, Any]:
+    """Build trace attributes for lease operations.
+    
+    Args:
+        lease_id: Lease ID
+        ttl: Lease TTL in seconds
+        remaining_ttl: Remaining TTL
+        **kwargs: Additional attributes
+        
+    Returns:
+        Dictionary of trace attributes
+    """
+    attrs = {
+        TraceAttributes.DB_SYSTEM: "etcd",
+    }
+    
+    if lease_id is not None:
+        attrs[TraceAttributes.ETCD_LEASE_ID] = lease_id
+    
+    if ttl is not None:
+        attrs[TraceAttributes.ETCD_LEASE_TTL] = ttl
+    
+    if remaining_ttl is not None:
+        attrs[TraceAttributes.ETCD_LEASE_REMAINING_TTL] = remaining_ttl
+    
+    attrs.update(kwargs)
+    return attrs
+
+
+def build_lock_attributes(
+    name: Optional[str] = None,
+    uuid: Optional[bytes] = None,
+    acquired: Optional[bool] = None,
+    **kwargs
+) -> Dict[str, Any]:
+    """Build trace attributes for lock operations.
+    
+    Args:
+        name: Lock name (key path)
+        uuid: Lock UUID (will use first 8 bytes)
+        acquired: Whether the lock was acquired
+        **kwargs: Additional attributes
+        
+    Returns:
+        Dictionary of trace attributes
+    """
+    attrs = {
+        TraceAttributes.DB_SYSTEM: "etcd",
+    }
+    
+    if name is not None:
+        attrs[TraceAttributes.ETCD_LOCK_NAME] = name
+    
+    if uuid is not None:
+        # Use first 8 bytes of UUID for readability
+        uuid_str = uuid[:8].hex() if isinstance(uuid, bytes) else str(uuid)[:16]
+        attrs[TraceAttributes.ETCD_LOCK_UUID] = uuid_str
+    
+    if acquired is not None:
+        attrs[TraceAttributes.ETCD_LOCK_ACQUIRED] = acquired
+    
+    attrs.update(kwargs)
+    return attrs
+
+
+def build_txn_attributes(
+    compare_count: Optional[int] = None,
+    success_count: Optional[int] = None,
+    failure_count: Optional[int] = None,
+    succeeded: Optional[bool] = None,
+    **kwargs
+) -> Dict[str, Any]:
+    """Build trace attributes for transaction operations.
+    
+    Args:
+        compare_count: Number of compare conditions
+        success_count: Number of success operations
+        failure_count: Number of failure operations
+        succeeded: Whether the transaction succeeded
+        **kwargs: Additional attributes
+        
+    Returns:
+        Dictionary of trace attributes
+    """
+    attrs = {
+        TraceAttributes.DB_SYSTEM: "etcd",
+    }
+    
+    if compare_count is not None:
+        attrs[TraceAttributes.ETCD_TXN_COMPARE_COUNT] = compare_count
+    
+    if success_count is not None:
+        attrs[TraceAttributes.ETCD_TXN_SUCCESS_COUNT] = success_count
+    
+    if failure_count is not None:
+        attrs[TraceAttributes.ETCD_TXN_FAILURE_COUNT] = failure_count
+    
+    if succeeded is not None:
+        attrs[TraceAttributes.ETCD_TXN_SUCCEEDED] = succeeded
+    
+    attrs.update(kwargs)
+    return attrs
+
+
+def build_batch_attributes(
+    size: int,
+    atomic: bool = False,
+    **kwargs
+) -> Dict[str, Any]:
+    """Build trace attributes for batch operations.
+    
+    Args:
+        size: Number of operations in the batch
+        atomic: Whether the batch is atomic
+        **kwargs: Additional attributes
+        
+    Returns:
+        Dictionary of trace attributes
+    """
+    attrs = {
+        TraceAttributes.DB_SYSTEM: "etcd",
+        TraceAttributes.ETCD_BATCH_SIZE: size,
+        TraceAttributes.ETCD_BATCH_ATOMIC: atomic,
+    }
+    
+    attrs.update(kwargs)
+    return attrs
+
+
+def build_endpoint_attributes(
+    endpoint: str,
+    **kwargs
+) -> Dict[str, Any]:
+    """Build trace attributes for endpoint-related operations.
+    
+    Args:
+        endpoint: The etcd endpoint
+        **kwargs: Additional attributes
+        
+    Returns:
+        Dictionary of trace attributes
+    """
+    attrs = {
+        TraceAttributes.ETCD_ENDPOINT: endpoint,
+    }
+    
+    attrs.update(kwargs)
+    return attrs
+
+
+def build_error_attributes(
+    error_code: Optional[str] = None,
+    error_message: Optional[str] = None,
+    **kwargs
+) -> Dict[str, Any]:
+    """Build trace attributes for error cases.
+    
+    Args:
+        error_code: Error code
+        error_message: Error message
+        **kwargs: Additional attributes
+        
+    Returns:
+        Dictionary of trace attributes
+    """
+    attrs = {}
+    
+    if error_code is not None:
+        attrs[TraceAttributes.ETCD_ERROR_CODE] = error_code
+    
+    if error_message is not None:
+        # Truncate long error messages
+        if len(error_message) > 256:
+            error_message = error_message[:256] + "..."
+        attrs[TraceAttributes.ETCD_ERROR_MESSAGE] = error_message
+    
+    attrs.update(kwargs)
+    return attrs

etcd3/transactions.py

@@ -0,0 +1,280 @@
+"""Transaction operations for etcd3.
+
+This module defines classes for building etcd transactions with
+comparison operations and conditional mutations.
+"""
+
+from typing import Any, Optional
+
+import etcdrpc
+import etcd3.utils as utils
+
+
+_OPERATORS = {
+    etcdrpc.Compare.EQUAL: "==",
+    etcdrpc.Compare.NOT_EQUAL: "!=",
+    etcdrpc.Compare.LESS: "<",
+    etcdrpc.Compare.GREATER: ">",
+}
+
+
+class BaseCompare:
+    """Base class for transaction comparison operations.
+
+    :param key: The key to compare
+    :type key: str or bytes
+    :param range_end: End of key range for range comparisons
+    :type range_end: str or bytes, optional
+    """
+
+    key: Any
+    range_end: Optional[Any]
+    value: Any
+    op: Optional[Any]
+
+    def __init__(self, key: Any, range_end: Optional[Any] = None) -> None:
+        self.key = key
+        self.range_end = range_end
+        self.value = None
+        self.op = None
+
+    def __eq__(self, other: Any) -> "BaseCompare":
+        """Set comparison to equal."""
+        self.value = other
+        self.op = etcdrpc.Compare.EQUAL
+        return self
+
+    def __ne__(self, other: Any) -> "BaseCompare":
+        """Set comparison to not equal."""
+        self.value = other
+        self.op = etcdrpc.Compare.NOT_EQUAL
+        return self
+
+    def __lt__(self, other: Any) -> "BaseCompare":
+        """Set comparison to less than."""
+        self.value = other
+        self.op = etcdrpc.Compare.LESS
+        return self
+
+    def __gt__(self, other: Any) -> "BaseCompare":
+        """Set comparison to greater than."""
+        self.value = other
+        self.op = etcdrpc.Compare.GREATER
+        return self
+
+    def __repr__(self) -> str:
+        """Return string representation of the comparison."""
+        if self.range_end is None:
+            keys = self.key
+        else:
+            keys = "[{}, {})".format(self.key, self.range_end)
+        return "{}: {} {} '{}'".format(
+            self.__class__, keys, _OPERATORS.get(self.op), self.value
+        )
+
+    def build_message(self) -> etcdrpc.Compare:
+        """Build the gRPC Compare message.
+
+        :returns: Compare message for the transaction
+        :rtype: etcdrpc.Compare
+        """
+        compare = etcdrpc.Compare()
+        compare.key = utils.to_bytes(self.key)
+        if self.range_end is not None:
+            compare.range_end = utils.to_bytes(self.range_end)
+
+        if self.op is None:
+            raise ValueError("op must be one of =, !=, < or >")
+
+        compare.result = self.op
+
+        self.build_compare(compare)
+        return compare
+
+    def build_compare(self, compare: etcdrpc.Compare) -> None:
+        """Build the target-specific comparison.
+
+        Override in subclasses to set the appropriate comparison target.
+
+        :param compare: The Compare message to populate
+        :type compare: etcdrpc.Compare
+        """
+        raise NotImplementedError
+
+
+class Value(BaseCompare):
+    """Compare the value of a key.
+
+    Example:
+        >>> transactions.Value('/key') == b'value'
+    """
+
+    def build_compare(self, compare: etcdrpc.Compare) -> None:
+        """Build a value comparison."""
+        compare.target = etcdrpc.Compare.VALUE
+        compare.value = utils.to_bytes(self.value)
+
+
+class Version(BaseCompare):
+    """Compare the version of a key.
+
+    Example:
+        >>> transactions.Version('/key') > 0
+    """
+
+    def build_compare(self, compare: etcdrpc.Compare) -> None:
+        """Build a version comparison."""
+        compare.target = etcdrpc.Compare.VERSION
+        compare.version = int(self.value)
+
+
+class Create(BaseCompare):
+    """Compare the creation revision of a key.
+
+    Example:
+        >>> transactions.Create('/key') == 0
+    """
+
+    def build_compare(self, compare: etcdrpc.Compare) -> None:
+        """Build a creation revision comparison."""
+        compare.target = etcdrpc.Compare.CREATE
+        compare.create_revision = int(self.value)
+
+
+class Mod(BaseCompare):
+    """Compare the modification revision of a key.
+
+    Example:
+        >>> transactions.Mod('/key') > 100
+    """
+
+    def build_compare(self, compare: etcdrpc.Compare) -> None:
+        """Build a modification revision comparison."""
+        compare.target = etcdrpc.Compare.MOD
+        compare.mod_revision = int(self.value)
+
+
+class Lease(BaseCompare):
+    """Compare the lease ID attached to a key.
+
+    Example:
+        >>> transactions.Lease('/key') == lease_id
+    """
+
+    def build_compare(self, compare: etcdrpc.Compare) -> None:
+        """Build a lease comparison."""
+        compare.target = etcdrpc.Compare.LEASE
+        compare.lease = int(self.value)
+
+
+class Put:
+    """A put operation for use in transactions.
+
+    :param key: The key to set
+    :type key: str or bytes
+    :param value: The value to set
+    :type value: str or bytes, optional
+    :param lease: Lease ID to associate with the key
+    :type lease: int, optional
+    :param prev_kv: Whether to return the previous key-value pair
+    :type prev_kv: bool
+    :param ignore_value: Whether to ignore the value field
+    :type ignore_value: bool
+    :param ignore_lease: Whether to ignore the lease field
+    :type ignore_lease: bool
+    """
+
+    key: Any
+    value: Optional[Any]
+    lease: Optional[int]
+    prev_kv: bool
+    ignore_value: bool
+    ignore_lease: bool
+
+    def __init__(
+        self,
+        key: Any,
+        value: Optional[Any] = None,
+        lease: Optional[int] = None,
+        prev_kv: bool = False,
+        ignore_value: bool = False,
+        ignore_lease: bool = False,
+    ) -> None:
+        self.key = key
+        self.value = value
+        self.lease = lease
+        self.prev_kv = prev_kv
+        self.ignore_value = ignore_value
+        self.ignore_lease = ignore_lease
+
+
+class Get:
+    """A get operation for use in transactions.
+
+    :param key: The key to get
+    :type key: str or bytes
+    :param range_end: End of key range for prefix queries
+    :type range_end: str or bytes, optional
+    """
+
+    key: Any
+    range_end: Optional[Any]
+
+    def __init__(self, key: Any, range_end: Optional[Any] = None) -> None:
+        self.key = key
+        self.range_end = range_end
+
+
+class Delete:
+    """A delete operation for use in transactions.
+
+    :param key: The key to delete
+    :type key: str or bytes
+    :param range_end: End of key range for range deletes
+    :type range_end: str or bytes, optional
+    :param prev_kv: Whether to return the deleted key-value pairs
+    :type prev_kv: bool
+    """
+
+    key: Any
+    range_end: Optional[Any]
+    prev_kv: bool
+
+    def __init__(
+        self,
+        key: Any,
+        range_end: Optional[Any] = None,
+        prev_kv: bool = False,
+    ) -> None:
+        self.key = key
+        self.range_end = range_end
+        self.prev_kv = prev_kv
+
+
+class Txn:
+    """A transaction with conditional operations.
+
+    Transactions allow atomic execution of a compare sequence
+    followed by success/failure operation lists.
+
+    :param compare: List of comparison operations
+    :type compare: list of BaseCompare
+    :param success: List of operations if all comparisons succeed
+    :type success: list of Put, Get, Delete, or Txn, optional
+    :param failure: List of operations if any comparison fails
+    :type failure: list of Put, Get, Delete, or Txn, optional
+    """
+
+    compare: list
+    success: Optional[list]
+    failure: Optional[list]
+
+    def __init__(
+        self,
+        compare: list,
+        success: Optional[list] = None,
+        failure: Optional[list] = None,
+    ) -> None:
+        self.compare = compare
+        self.success = success
+        self.failure = failure