ms-common-py 0.2.0

A comprehensive APM and instrumentation library for Python microservices

MS Common Python Library

A comprehensive Application Performance Monitoring (APM) and instrumentation library for Python microservices at FinAccel.

Features

• APM Instrumentation: Automatic tracing and monitoring with Datadog integration
• Exception Handling: Standardized exception classes for microservices
• Configuration Management: Thread-safe configuration management for APM settings
• Class Instrumentation: Automatic instrumentation of class methods
• Function Decorators: Easy-to-use decorators for tracing individual functions

Installation

pip install ms-common-py

Quick Start

Basic Function Tracing

from apm import trace

@trace(name="my_function", service="my-service")
def my_function():
    # Your code here
    return "Hello World"

Class Instrumentation

from apm import instrument_class

@instrument_class(prefix="MyService", service="my-service")
class MyService:
    def process_data(self):
        # This method will be automatically traced
        pass
    
    def validate_input(self):
        # This method will also be traced
        pass

Configuration

Set the following environment variables:

# APM Configuration
export APM_PROVIDER=datadog
export DD_SERVICE=my-service-name
export DD_ENV=production
export APM_VERSION=1.0.0
export DD_APM_ENABLED=true

# Datadog Agent Configuration (optional)
export DD_AGENT_HOST=localhost
export DD_TRACE_AGENT_PORT=8126

APM Configuration

The library uses a thread-safe singleton configuration that automatically refreshes when environment variables change:

from apm.const import APMConfig

# Get current configuration
config = APMConfig.get()
print(f"Service: {config.service_name}")
print(f"Environment: {config.environment}")
print(f"Enabled: {config.enabled}")

# Force refresh configuration
config = APMConfig.get(force=True)

Exception Handling

Use standardized exceptions for consistent error handling across services:

from apm.exceptions import (
    ServiceException,
    AuthenticationFailure,
    ForbiddenException,
    BadRequestException,
    NotFoundException
)

# Raise a custom service exception
raise AuthenticationFailure(
    message="Invalid credentials",
    service="my-service"
)

Advanced Usage

Custom Tags and Resource Names

from apm import trace

@trace(
    name="complex_operation",
    service="data-processor",
    resource="process_user_data",
    tags={"operation_type": "batch", "version": "v2"}
)
def process_user_data(user_id):
    # Your processing logic
    pass

Excluding Methods from Class Instrumentation

from apm import instrument_class

@instrument_class(
    prefix="UserService",
    exclude_methods=["_private_method", "health_check"]
)
class UserService:
    def create_user(self):
        # This will be traced
        pass
    
    def _private_method(self):
        # This will NOT be traced
        pass
    
    def health_check(self):
        # This will NOT be traced
        pass

Service Type Auto-Detection

The library automatically detects service types based on class inheritance:

• Consumer: Classes inheriting from BaseConsumer or Consumer
• Cron: Classes inheriting from BaseCommand or Command
• API: Classes inheriting from APIView, ViewSet, or Handler
• Worker: Classes inheriting from Worker or Task
• Service: Default for other classes

Available Exception Classes

Exception	HTTP Code	Description
ServiceException	500	Base exception class
AuthenticationFailure	401	Authentication failed
ForbiddenException	403	Access forbidden
BadRequestException	400	Bad request
MissingParamException	406	Missing required parameters
ValidateException	422	Validation error
NotFoundException	404	Resource not found
BusinessException	422	Business logic error
ProductClosedException	450	Product/service closed
BillNotValidException	451	Bill validation error

Requirements

• Python 3.9+
• ddtrace>=2.2.0 (for Datadog integration)

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

This project is proprietary to FinAccel.

Support

For issues and questions, please contact the FinAccel development team or create an issue in the Bitbucket repository.