Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

7.5 KB
Raw Blame
from typing import Optional, cast

from products.warehouse_sources.sources.cloudzero._config import CloudzeroSourceConfig
from products.warehouse_sources.sources.cloudzero.cloudzero import (
    KEY_REJECTED_MESSAGE,
    CloudzeroResumeConfig,
    cloudzero_source,
    validate_credentials as validate_cloudzero_credentials,
)
from products.warehouse_sources.sources.cloudzero.settings import (
    COST_TYPE_OPTIONS,
    ENDPOINTS,
    GRANULARITY_OPTIONS,
    INCREMENTAL_FIELDS,
    PARTITION_KEYS,
    PRIMARY_KEYS,
)
from products.warehouse_sources.sources.sdk import (
    CanonicalDescriptions,
    DataWarehouseSourceCategory,
    ExternalDataSourceType,
    FieldType,
    ReleaseStatus,
    ResumableSource,
    ResumableSourceManager,
    SourceConfig,
    SourceFieldInputConfig,
    SourceFieldInputConfigType,
    SourceFieldSelectConfig,
    SourceFieldSelectConfigOption,
    SourceInputs,
    SourceRegistry,
    SourceResponse,
    SourceSchema,
    build_endpoint_schemas,
    detect,
)


def _parse_group_by(group_by: str | None) -> list[str]:
    if not group_by:
        return []
    return [dimension.strip() for dimension in group_by.split(",") if dimension.strip()]


@SourceRegistry.register
class CloudzeroSource(ResumableSource[CloudzeroSourceConfig, CloudzeroResumeConfig]):
    codebase_detection = detect(env=("^CLOUDZERO_",))

    lists_tables_without_credentials = True  # static endpoint catalog — safe for public docs
    supported_versions = ("v2",)
    default_version = "v2"
    api_docs_url = "https://docs.cloudzero.com/reference"

    @property
    def source_type(self) -> ExternalDataSourceType:
        return ExternalDataSourceType.CLOUDZERO

    def get_non_retryable_errors(self) -> dict[str, str | None]:
        return {
            "403 Client Error: Forbidden": KEY_REJECTED_MESSAGE,
            "Unauthorized": KEY_REJECTED_MESSAGE,
            "410 Client Error: Gone": (
                "CloudZero's paged result cache expired (results are only valid for 24 hours). "
                "Please retry the sync to start a fresh query."
            ),
        }

    def get_canonical_descriptions(self) -> CanonicalDescriptions:
        from products.warehouse_sources.sources.cloudzero.canonical_descriptions import CANONICAL_DESCRIPTIONS

        return CANONICAL_DESCRIPTIONS

    def get_schemas(
        self,
        config: CloudzeroSourceConfig,
        team_id: int,
        with_counts: bool = False,
        names: list[str] | None = None,
        force_refresh: bool = False,
        api_version: str | None = None,
    ) -> list[SourceSchema]:
        return build_endpoint_schemas(ENDPOINTS, INCREMENTAL_FIELDS, names)

    def validate_credentials(
        self,
        config: CloudzeroSourceConfig,
        team_id: int,
        schema_name: Optional[str] = None,
        api_version: str | None = None,
    ) -> tuple[bool, str | None]:
        return validate_cloudzero_credentials(config.api_key)

    def get_resumable_source_manager(self, inputs: SourceInputs) -> ResumableSourceManager[CloudzeroResumeConfig]:
        return ResumableSourceManager[CloudzeroResumeConfig](inputs, CloudzeroResumeConfig)

    def source_for_pipeline(
        self,
        config: CloudzeroSourceConfig,
        resumable_source_manager: ResumableSourceManager[CloudzeroResumeConfig],
        inputs: SourceInputs,
    ) -> SourceResponse:
        group_by = _parse_group_by(config.group_by)
        resource = cloudzero_source(
            api_key=config.api_key,
            endpoint=inputs.schema_name,
            team_id=inputs.team_id,
            job_id=inputs.job_id,
            resumable_source_manager=resumable_source_manager,
            should_use_incremental_field=inputs.should_use_incremental_field,
            db_incremental_field_last_value=inputs.db_incremental_field_last_value
            if inputs.should_use_incremental_field
            else None,
            granularity=config.granularity,
            cost_type=config.cost_type,
            group_by=group_by,
        )

        primary_keys = ["usage_date", *group_by] if inputs.schema_name == "Costs" else PRIMARY_KEYS[inputs.schema_name]
        partition_key = PARTITION_KEYS.get(inputs.schema_name)

        return SourceResponse(
            name=resource.name,
            items=lambda: resource,
            primary_keys=primary_keys,
            column_hints=resource.column_hints,
            partition_count=1 if partition_key else None,
            partition_size=1 if partition_key else None,
            partition_mode="datetime" if partition_key else None,
            partition_format="month" if partition_key else None,
            partition_keys=[partition_key] if partition_key else None,
        )

    @property
    def get_source_config(self) -> SourceConfig:
        return SourceConfig(
            name=ExternalDataSourceType.CLOUDZERO,
            category=DataWarehouseSourceCategory.FINANCE___ACCOUNTING,
            label="CloudZero",
            caption=(
                "Enter your CloudZero API key. Grant it `billing:read_dimensions` so PostHog can check "
                "the connection, then add a scope for each table you want to sync: `billing:read_costs` "
                "for costs, `budgets:read_budgets` for budgets, `insights:read_insights` for insights, "
                "and `optimize:list_recommendations` plus `optimize:list_recommendation_types` for "
                "recommendations. You set these in CloudZero under Settings > API Keys."
            ),
            docsUrl="https://posthog.com/docs/cdp/sources/cloudzero",
            iconPath="/static/services/cloudzero.png",
            releaseStatus=ReleaseStatus.BETA,
            keywords=["cloud cost", "finops", "billing"],
            fields=cast(
                list[FieldType],
                [
                    SourceFieldInputConfig(
                        name="api_key",
                        label="API key",
                        type=SourceFieldInputConfigType.PASSWORD,
                        required=True,
                        placeholder="",
                        secret=True,
                    ),
                    SourceFieldSelectConfig(
                        name="granularity",
                        sync_setting=True,
                        label="Granularity",
                        required=True,
                        defaultValue="daily",
                        options=[
                            SourceFieldSelectConfigOption(label=option.capitalize(), value=option)
                            for option in GRANULARITY_OPTIONS
                        ],
                    ),
                    SourceFieldSelectConfig(
                        name="cost_type",
                        sync_setting=True,
                        label="Cost type",
                        required=True,
                        defaultValue="real_cost",
                        options=[
                            SourceFieldSelectConfigOption(label=option.replace("_", " ").capitalize(), value=option)
                            for option in COST_TYPE_OPTIONS
                        ],
                    ),
                    SourceFieldInputConfig(
                        name="group_by",
                        sync_setting=True,
                        label="Group costs by dimensions (optional)",
                        type=SourceFieldInputConfigType.TEXT,
                        required=False,
                        placeholder="e.g. service,account",
                        secret=False,
                    ),
                ],
            ),
        )