sumologic provider for stackql
This repository is used to generate and document the sumologic provider for StackQL, allowing you to query and manipulate Sumo Logic resources using SQL-like syntax. The provider is built using the @stackql/provider-utils package, which provides tools for converting OpenAPI specifications into StackQL-compatible provider schemas.
To use the Sumo Logic provider with StackQL, you'll need:
- A Sumo Logic account with appropriate API credentials
- Sumo Logic Access ID and Access Key with sufficient permissions for the resources you want to access
- StackQL CLI installed on your system (see StackQL)
First, download the Sumo Logic API OpenAPI specification:
rm -rf provider-dev/downloaded/*
curl -L https://api.sumologic.com/docs/sumologic-openapi.yaml \
-o provider-dev/downloaded/sumologic-openapi.yaml
# Convert YAML to JSON if needed
python3 provider-dev/scripts/yaml_to_json.py \
--input provider-dev/downloaded/sumologic-openapi.yaml \
--output provider-dev/downloaded/openapi.jsonNext, split the monolithic OpenAPI specification into service-specific files:
rm -rf provider-dev/source/*
npm run split -- \
--provider-name sumologic \
--api-doc provider-dev/downloaded/openapi.json \
--svc-discriminator tag \
--output-dir provider-dev/source \
--overwrite \
--svc-name-overrides "$(cat <<EOF
{
"log-searches": "logs",
"content-management": "content",
"user-management": "users",
"roles-management": "roles",
"dashboard-management": "dashboards",
"connections-management": "connections",
"ingest-budgets": "ingest",
"scheduled-views": "views"
}
EOF
)"Generate the mapping configuration that connects OpenAPI operations to StackQL resources:
npm run generate-mappings -- \
--provider-name sumologic \
--input-dir provider-dev/source \
--output-dir provider-dev/configUpdate the resultant provider-dev/config/all_services.csv to add the stackql_resource_name, stackql_method_name, stackql_verb values for each operation.
This step transforms the split OpenAPI service specs into a fully-functional StackQL provider by applying the resource and method mappings defined in your CSV file.
rm -rf provider-dev/openapi/*
npm run generate-provider -- \
--provider-name sumologic \
--input-dir provider-dev/source \
--output-dir provider-dev/openapi/src/sumologic \
--config-path provider-dev/config/all_services.csv \
--servers '[{"url": "https://api.sumologic.com/api"}]' \
--provider-config '{"auth": {"type": "basic", "credentials": {"usernameEnvVar": "SUMOLOGIC_ACCESS_ID", "passwordEnvVar": "SUMOLOGIC_ACCESS_KEY"}}}' \
--overwriteBefore running tests, start a StackQL server with your provider:
PROVIDER_REGISTRY_ROOT_DIR="$(pwd)/provider-dev/openapi"
npm run start-server -- --provider sumologic --registry $PROVIDER_REGISTRY_ROOT_DIRTest all metadata routes (services, resources, methods) in the provider:
npm run test-meta-routes -- sumologic --verboseWhen you're done testing, stop the StackQL server:
npm run stop-serverUse this command to view the server status:
npm run server-statusRun some test queries against the provider using the stackql shell:
PROVIDER_REGISTRY_ROOT_DIR="$(pwd)/provider-dev/openapi"
REG_STR='{"url": "file://'${PROVIDER_REGISTRY_ROOT_DIR}'", "localDocRoot": "'${PROVIDER_REGISTRY_ROOT_DIR}'", "verifyConfig": {"nopVerify": true}}'
./stackql shell --registry="${REG_STR}"Example queries to try:
-- Get collector information
SELECT
id,
name,
category,
alive,
ephemeral,
host_name,
source_sync_mode,
time_zone
FROM sumologic.collectors.collectors;
-- List all dashboards
SELECT
id,
title,
description,
folder_id,
created_at,
modified_at,
created_by,
modified_by
FROM sumologic.dashboards.dashboards;
-- Get ingest budget information
SELECT
id,
name,
field_value,
capacity_bytes,
timezone,
reset_time,
description,
action
FROM sumologic.ingest.budgets;
-- View user details
SELECT
id,
first_name,
last_name,
email,
is_active,
is_locked,
role_ids
FROM sumologic.users.users;
-- Check scheduled searches
SELECT
id,
name,
description,
query_text,
time_range,
schedule,
schedule_type,
parsing_mode
FROM sumologic.logs.searches;To publish the provider push the sumologic dir to providers/src in a feature branch of the stackql-provider-registry. Follow the registry release flow.
Launch the StackQL shell:
export DEV_REG="{ \"url\": \"https://registry-dev.stackql.app/providers\" }"
./stackql --registry="${DEV_REG}" shellPull the latest dev sumologic provider:
registry pull sumologic;Run some test queries to verify the provider works as expected.
Provider doc microsites are built using Docusaurus and published using GitHub Pages.
a. Update headerContent1.txt and headerContent2.txt accordingly in provider-dev/docgen/provider-data/
b. Update the following in website/docusaurus.config.js:
// Provider configuration - change these for different providers
const providerName = "sumologic";
const providerTitle = "Sumo Logic Provider";c. Then generate docs using...
npm run generate-docs -- \
--provider-name sumologic \
--provider-dir ./provider-dev/openapi/src/sumologic/v00.00.00000 \
--output-dir ./website \
--provider-data-dir ./provider-dev/docgen/provider-datacd website
# test build
yarn build
# run local dev server
yarn startUnder Pages in the repository, in the Build and deployment section select GitHub Actions as the Source. In Netlify DNS create the following records:
| Source Domain | Record Type | Target |
|---|---|---|
| sumologic-provider.stackql.io | CNAME | stackql.github.io. |
MIT
Contributions are welcome! Please feel free to submit a Pull Request.