telemetrx 0.2.1
a package for sending app telemetry data to the TelemetrX backend. Compatible with TelemetrX Fast API v0.3.0 with SSL bypass support for corporate environments.
Requires Python: >=3.10

# telemetrx-0.2.1

telemetrx is a Python library which facilitates the sending of App telemetry data to the TelemetrX platform, leveraging the TelemetrX API.

**🆕 Version 0.2.1 - Fast API v0.3.0 Compatibility + SSL Bypass**
- Updated API endpoint structure (`/v1/send`)
- New governance fields: `usage_type`, `app_action`, `srid`
- Enhanced technology stripe validation
- Improved error handling and response parsing
- Async function support with `send_telemetrx_async`
- **🔒 SSL bypass support for corporate environments** (`verify_ssl=False`) 

## Features

The library features the function send_telemetrx() which helps app owners to send telemetry data to the TelemetrX platform with a single line of code. 

## Installation

Install telemetrx with pip:

```bash
pip install telemetrx
```

## Quick Start

Before you start, there are few environment variables that will need to be set:

- BASE_URL_ENV = <Telemetrx API URL for ENV>

    Where ENV is either DEV, PROD or STAGE depending on which environment your app is sending data to. 
    If you are unsure what value to set in this environment variable, please contact visimard@cisco.com or vivekksi@cisco.com or anpapath@cisco.com. 

- TELEMETRX_API_KEY = <Your app's API key for TelemetrX>

    This is the app token you have received when registering your app with TelemetrX. If you do not know your app key or have lost/forgotten it, please contact visimard@cisco.com or vivekksi@cisco.com or anpapath@cisco.com

After you make sure that the environment variables above are set, here is an example of how to use the telemetrx library:

```python
from telemetrx import send_telemetrx

# Basic usage
telemetry_data = {"search_query": "network troubleshooting",
                  "result_count": 25}

send_telemetrx(
    user="your_cec_id",
    app_name="My app",
    telemetry_data=telemetry_data,
    telemetrx_env="prod",
    technology_stripe="Enterprise Networking",
    app_action="search_performed",
    usage_type="Active",  # "Active" for user clicks, "Passive" for auto-loads
    srid="SR123456789"  # Optional Service Request ID
)
```

### New Features in v0.2.0

**Enhanced Governance Fields:**
- `usage_type`: "Active" (intentional user action) or "Passive" (automatic/background)
- `app_action`: Specific action performed (e.g., "search", "login", "export")
- `srid`: Service Request ID for tracking

**Updated Technology Stripes:**
Now supports: "Data Center", "Collaboration", "Security", "Service Provider", "Enterprise Networking", "Other", "SaaS", "Technology Agnostic"

**Async Support:**
```python
import asyncio
from telemetrx import send_telemetrx_async

async def send_data():
    result = await send_telemetrx_async(
        telemetrx_env="stage",
        telemetrx_data={"data": {"app_name": "your_app", "cec": "your_cec_id"}},
        app_token="your_app_token",
        telemetrx_base_url="https://your-telemetrx-api-url.com"
    )
    return result

# Run async
result = asyncio.run(send_data())
```

## Corporate Environment Support

**🔒 SSL Bypass for Corporate Networks**

Version 0.2.1 introduces SSL bypass support for corporate environments where self-signed certificates may cause connection issues.

### Usage

```python
from telemetrx import send_telemetrx

# For corporate environments with SSL certificate issues
result = send_telemetrx(
    user="your_cec_id",
    app_name="your_app_name",
    telemetry_data={"action": "user_login", "timestamp": "2024-01-01T12:00:00Z"},
    technology_stripe="Technology Agnostic",
    app_action="login",
    usage_type="Active",
    verify_ssl=False,  # Disable SSL verification for corporate environments
    app_token="your_app_token",
    telemetrx_base_url="https://your-telemetrx-api-url.com",
    telemetrx_env="stage"
)
```

### Async Usage with SSL Bypass

```python
import asyncio
from telemetrx import send_telemetrx_async

async def send_data():
    payload = {
        "data": {
            "app_name": "your_app_name",
            "cec": "your_cec_id",
            "technology_stripe": "Technology Agnostic",
            "custom": {"action": "user_action"},
            "app_action": "test_action",
            "usage_type": "Active"
        }
    }
    
    result = await send_telemetrx_async(
        telemetrx_env="stage",
        telemetrx_data=payload,
        app_token="your_app_token",
        telemetrx_base_url="https://your-telemetrx-api-url.com",
        verify_ssl=False  # Disable SSL verification
    )
    return result

result = asyncio.run(send_data())
```

**⚠️ Security Note**: Only use `verify_ssl=False` in trusted corporate environments. This disables SSL certificate verification and should not be used in production environments with untrusted networks.

## Requirements

- Python 3.10+

## License

Distributed under a propriatery license. See LICENSE file for more information. 

## Authors

- Vivek Singh - vivekksi
- Vincent Simard - visimard
- Angeliki Papathanasiou - anpapath