{"id":26150281,"url":"https://github.com/treblle/treblle-kong","last_synced_at":"2026-03-07T01:02:42.582Z","repository":{"id":276634975,"uuid":"929831106","full_name":"Treblle/treblle-kong","owner":"Treblle","description":"Kong API Gateway plugin for Treblle","archived":false,"fork":false,"pushed_at":"2026-01-14T09:14:17.000Z","size":57,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-14T13:28:46.932Z","etag":null,"topics":["kong-api-gateway","kong-plugin","treblle","treblle-sdk"],"latest_commit_sha":null,"homepage":"https://treblle.com","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Treblle.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-09T14:07:48.000Z","updated_at":"2026-01-14T09:14:21.000Z","dependencies_parsed_at":"2025-03-27T12:24:15.010Z","dependency_job_id":"d5387188-7aee-4ac9-8cc9-ad13f029e8e6","html_url":"https://github.com/Treblle/treblle-kong","commit_stats":null,"previous_names":["treblle/treblle-kong"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/Treblle/treblle-kong","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Treblle%2Ftreblle-kong","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Treblle%2Ftreblle-kong/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Treblle%2Ftreblle-kong/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Treblle%2Ftreblle-kong/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Treblle","download_url":"https://codeload.github.com/Treblle/treblle-kong/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Treblle%2Ftreblle-kong/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30204452,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T19:07:06.838Z","status":"ssl_error","status_checked_at":"2026-03-06T18:57:34.882Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kong-api-gateway","kong-plugin","treblle","treblle-sdk"],"created_at":"2025-03-11T05:55:01.059Z","updated_at":"2026-03-07T01:02:42.520Z","avatar_url":"https://github.com/Treblle.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://github.com/user-attachments/assets/54f0c084-65bb-4431-b80d-cceab6c63dc3\"/\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n# Treblle\n\n\u003ca href=\"http://treblle.com/\" target=\"_blank\"\u003eWebsite\u003c/a\u003e\n\u003cspan\u003e\u0026nbsp;\u0026nbsp;•\u0026nbsp;\u0026nbsp;\u003c/span\u003e\n\u003ca href=\"https://docs.treblle.com\" target=\"_blank\"\u003eDocumentation\u003c/a\u003e\n\u003cspan\u003e\u0026nbsp;\u0026nbsp;•\u0026nbsp;\u0026nbsp;\u003c/span\u003e\n\u003ca href=\"https://docs.treblle.com/en/integrations\" target=\"_blank\"\u003eIntegrations\u003c/a\u003e\n\n  \u003chr /\u003e\n\u003c/div\u003e\n\n## API Intelligence Platform\n\nTreblle is a federated API intelligence platform that helps organizations understand their entire API landscape in less than 60 seconds.\n\n\u003cdiv align=\"center\"\u003e\n\u003ca href=\"https://treblle.com/product/api-observability\" target=\"_blank\"\u003eAPI Intelligence\u003c/a\u003e\n\u003cspan\u003e\u0026nbsp;\u0026nbsp;•\u0026nbsp;\u0026nbsp;\u003c/span\u003e\n\u003ca href=\"https://treblle.com/product/api-documentation\" target=\"_blank\"\u003eAPI Documentation\u003c/a\u003e\n\u003cspan\u003e\u0026nbsp;\u0026nbsp;•\u0026nbsp;\u0026nbsp;\u003c/span\u003e\n\u003ca href=\"https://treblle.com/product/api-analytics\" target=\"_blank\"\u003eAPI Analytics\u003c/a\u003e\n\u003cspan\u003e\u0026nbsp;\u0026nbsp;•\u0026nbsp;\u0026nbsp;\u003c/span\u003e\n\u003ca href=\"https://treblle.com/product/api-governance\" target=\"_blank\"\u003eAPI Governance\u003c/a\u003e\n\u003cspan\u003e\u0026nbsp;\u0026nbsp;•\u0026nbsp;\u0026nbsp;\u003c/span\u003e\n\u003ca href=\"https://treblle.com/product/api-security\" target=\"_blank\"\u003eAPI Security\u003c/a\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cbr /\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/9b5f40ba-bec9-414b-af88-f1c1cc80781b\"/\u003e\n  \u003cbr /\u003e\n\u003c/div\u003e\n\n# Kong Gateway Plugin for Treblle\n\nThe Kong API Gateway plugin for Treblle captures API requests in real time and sends that data to Treblle for monitoring and analysis.\n\n### What Treblle Helps You With\n\n- Understand who your API consumers are, how they're using the API, and when\n- Stay secure and compliant at design and run-time\n- Automate API governance checks across security, performance, and design\n- Debug APIs in real-time with access to request/response payloads\n- Generate and update your API documentation in OpenAPI Spec format\n- Build your API developer portal with an AI-powered integration assistant\n- Test your APIs in a fast and easy way\n- And much more\n\n### Terminology\n\n- `plugin`: a plugin executing actions inside Kong before or after a request has been proxied to the upstream API.\n- `Service`: the Kong entity representing an external upstream API or microservice.\n- `Route`: The Kong entity represents a way to map downstream requests to upstream services.\n- `Consumer`: the Kong entity representing a developer or machine using the API. When using Kong, a Consumer only communicates with Kong, which proxies every call to the upstream API.\n- `Credential`: a unique string associated with a Consumer, also called an API key.\n- `Upstream service`: refers to your own API/service sitting behind Kong, to which client requests are forwarded.\n- `API`: a legacy entity representing your upstream services. Deprecated in favor of Services since CE 0.13.0 and EE 0.32.\n\n# Installation Options\n\nThis plugin can be installed on various environments. Below you'll find installation instructions for:\n\n- [MacOS using Docker](#installation-on-macos-using-docker)\n- [Linux using Docker](#installation-on-linux-using-docker)\n\nChoose the option that fits your environment.\n\n# Installation on MacOS Using Docker\n\n### Prerequisites\n\n- Docker Desktop installed on your Mac\n- Git installed\n- A Treblle account with an API key and Project ID\n\n### Step 1: Clone the Repository\n\n```bash\ngit clone https://github.com/Treblle/treblle-kong.git\ncd treblle-kong\n```\n\n### Step 2: Build the Docker Image\n\nWe'll use the [Dockerfile](https://github.com/Treblle/treblle-kong/blob/main/Dockerfile) in the plugin folder to build a custom image of Kong with the Treblle plugin enabled:\n\n```bash\ndocker build -t k:v1 .\n```\n\nThis creates a custom Kong image tagged as \"k\" with the installed Treblle plugin.\n\n### Step 3: Start the Container\n\nRun Docker Compose to start the Kong container with the plugin:\n\n```bash\ndocker-compose up -d\n```\n\nAfter this step, your Kong Gateway should be up and running with the Treblle plugin enabled.\n\n## Configuration Using Curl (MacOS)\n\n### 1. Verify Plugin is Enabled\n\nRead the [Plugin Reference](https://docs.konghq.com/gateway-oss/2.4.x/admin-api/#add-plugin) and the [Plugin Precedence](https://docs.konghq.com/gateway-oss/2.4.x/admin-api/#precedence) sections for more information.\n\n```bash\ncurl -i -X GET http://localhost:8001/plugins/enabled\n```\n\n### 2. Create a Service\n\nConfigure this plugin on a [Service](https://docs.konghq.com/gateway-oss/2.4.x/admin-api/#service-object) by making the following request on your Kong server:\n\n```bash\ncurl -i -X POST http://localhost:8001/services \\\n  --data \"name=httpbin-service\" \\\n  --data \"url=https://httpbin.org\"\n```\n\n### 3. Create a Route\n\nConfigure this plugin on a [Route](https://docs.konghq.com/gateway-oss/2.4.x/admin-api/#route-object) with:\n\n```bash\ncurl -i -X POST http://localhost:8001/services/httpbin-service/routes \\\n  --data \"name=httpbin-route-post\" \\\n  --data \"paths[]=/httpbin\" \\\n  --data \"methods[]=POST\"\n```\n\n### 4. Create an API on Treblle and Get Credentials\n\nFirst, you need to create an API on the Treblle platform to get your API key and Project ID, which will be used to configure the plugin in the next step.\n\n- Visit the [Treblle](https://treblle.com) Dashboard to create a new API\n- Note your `TREBLLE_API_KEY` and `TREBLLE_PROJECT_ID`\n\n### 5. Add Treblle Plugin to Service\n\nThe `mask_keywords` are the sensitive data fields that will be masked before being sent to Treblle. This important security feature protects sensitive information in your API traffic.\n\n```bash\ncurl -i -X POST http://localhost:8001/services/httpbin-service/plugins \\\n  --data \"name=treblle\" \\\n  --data \"config.api_key=YOUR_TREBLLE_API_KEY\" \\\n  --data \"config.project_id=YOUR_TREBLLE_PROJECT_ID\" \\\n  --data \"config.mask_keywords[]=Authorization\" \\\n  --data \"config.mask_keywords[]=User-Agent\" \\\n  --data \"config.mask_keywords[]=Cookie\"\n```\n\n### 6. Test Publishing to Treblle\n\n```bash\ncurl -i -X POST http://localhost:8000/httpbin/post \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"test\": \"v1final3d\", \"foo\": \"bar\"}'\n```\n\nAt this point, you should be able to go to your Treblle dashboard and see the API request that was just made, complete with all the details captured by the plugin.\n\n# Installation on Linux Using Docker\n\n### Project Structure\n\n```\nkong-treblle-sandbox/\n│\n├── docker-compose.yml\n├── kong.conf\n├── Dockerfile\n└── kong.yml\n```\n\n### Prerequisites\n\n- Docker installed on your Linux system\n- Git installed\n- A Treblle account with an API key and Project ID\n\n## Configuration Files\n\n### 1. Dockerfile\n\nCreate a `Dockerfile` with the following content. This file builds a custom Kong image with the Treblle plugin installed:\n\n```dockerfile\nFROM kong:3.4.0\n\nUSER root\n\n# Install dependencies\nRUN apk add --no-cache \\\n    git \\\n    unzip \\\n    curl \\\n    luarocks\n\n# Install the Treblle plugin\nRUN luarocks install --server=http://luarocks.org/manifests/treblle kong-plugin-treblle\n\n# Copy Kong configuration\nCOPY kong.conf /etc/kong/kong.conf\n\nUSER kong\n```\n\n### 2. Kong Configuration (kong.conf)\n\nCreate a `kong.conf` file with the following content. This configuration file sets up the database connection and enables the Treblle plugin:\n\n```ini\ndatabase = on\npg_host = postgres\npg_port = 5432\npg_user = kong\npg_password = kong\npg_database = kong\nplugins = bundled,treblle\n```\n\n### 3. Docker Compose (docker-compose.yml)\n\nCreate a `docker-compose.yml` file with the following content. This file orchestrates the containers needed for Kong and its database:\n\n```yaml\nservices:\n  postgres:\n    image: postgres:13\n    environment:\n      POSTGRES_DB: kong\n      POSTGRES_PASSWORD: kong\n      POSTGRES_USER: kong\n    volumes:\n      - postgres_data:/var/lib/postgresql/data\n    healthcheck:\n      test: [\"CMD\", \"pg_isready\", \"-U\", \"kong\"]\n      interval: 30s\n      timeout: 30s\n      retries: 3\n\n  kong-migration:\n    image: kong:3.4.0\n    command: kong migrations bootstrap\n    environment:\n      KONG_DATABASE: postgres\n      KONG_PG_HOST: postgres\n      KONG_PG_PASSWORD: kong\n      KONG_PG_USER: kong\n    depends_on:\n      postgres:\n        condition: service_healthy\n\n  kong:\n    build: \n      context: .\n      dockerfile: Dockerfile\n    container_name: kong-treblle\n    environment:\n      KONG_DATABASE: postgres\n      KONG_PG_HOST: postgres\n      KONG_PG_PASSWORD: kong\n      KONG_PG_USER: kong\n      KONG_PLUGINS: bundled,treblle\n      KONG_PROXY_ACCESS_LOG: /dev/stdout\n      KONG_ADMIN_ACCESS_LOG: /dev/stdout\n      KONG_PROXY_ERROR_LOG: /dev/stderr\n      KONG_ADMIN_ERROR_LOG: /dev/stderr\n      KONG_ADMIN_LISTEN: 0.0.0.0:8001, 0.0.0.0:8444 ssl\n    ports:\n      - \"9000:8000\"   # Proxy port\n      - \"9001:8001\"   # Admin API port\n      - \"9443:8443\"\n      - \"9444:8444\"\n    depends_on:\n      postgres:\n        condition: service_healthy\n      kong-migration:\n        condition: service_completed_successfully\n    healthcheck:\n      test: [\"CMD\", \"kong\", \"health\"]\n      interval: 10s\n      timeout: 10s\n      retries: 10\n\nvolumes:\n  postgres_data:\n```\n\n### 4. Declarative Configuration (kong.yml)\n\nOptionally, create a `kong.yml` file for declarative configuration. This file provides a way to define services and routes in a declarative manner:\n\n```yaml\n_format_version: \"3.0\"\n\nservices:\n - name: test-service\n   url: https://httpbin.org\n   routes:\n     - name: test-route\n       paths:\n         - /test\n```\n\n## Installation Steps (Linux)\n\n### 1. Prepare Project Directory\n\n```bash\nmkdir kong-treblle-sandbox\ncd kong-treblle-sandbox\n```\n\n### 2. Initialize Docker Containers\n\n```bash\ndocker-compose up -d\n```\n\n### 3. Create a Service in Kong\n\n```bash\ncurl -i -X POST http://localhost:9001/services \\\n  --data name=httpbin-service \\\n  --data url=https://httpbin.org\n```\n\n### 4. Create Route\n\n```bash\ncurl -i -X POST http://localhost:9001/services/httpbin-service/routes \\\n  --data \"name=httpbin-route\" \\\n  --data \"paths[]=/test\" \\\n  --data \"methods[]=POST\"\n```\n\n### 5. Enable Treblle Plugin\n\n```bash\ncurl -i -X POST http://localhost:9001/services/httpbin-service/plugins \\\n  --data \"name=treblle\" \\\n  --data \"config.api_key=YOUR_TREBLLE_API_KEY\" \\\n  --data \"config.project_id=YOUR_TREBLLE_PROJECT_ID\" \\\n  --data \"config.mask_keywords[]=Authorization\" \\\n  --data \"config.mask_keywords[]=API_Key\" \\\n  --data \"config.mask_keywords[]=Secure-Token\"\n```\n\n## Testing (Linux)\n\n```bash\n# Test route\ncurl -X POST http://localhost:9000/test/post\n```\n\n# Troubleshooting\n\n## MacOS Troubleshooting\n\n### Enable Debug Logs\n\nIf you want to print Treblle debug logs, set `config.debug=true` when enabling the plugin:\n\n```bash\ncurl -i -X POST http://localhost:8001/services/httpbin-service/plugins \\\n  --data \"name=treblle\" \\\n  --data \"config.api_key=YOUR_TREBLLE_API_KEY\" \\\n  --data \"config.project_id=YOUR_TREBLLE_PROJECT_ID\" \\\n  --data \"config.debug=true\"\n```\n\n## Linux Troubleshooting\n\n### Verification Commands\n\n```bash\n# Check Docker containers\ndocker-compose ps\n\n# View Kong logs\ndocker-compose logs kong\n\n# Test route\ncurl -X POST http://localhost:9000/test/post\n```\n\n### Cleanup\n\n```bash\n# Stop and remove containers\ndocker-compose down\n\n# Remove volumes (optional)\ndocker-compose down -v\n```\n\n# Configuration Parameters\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| name | | The name of the plugin, in this case `treblle` |\n| config.api_key | | The Treblle SDK token provided by Treblle |\n| config.project_id | | The Treblle API ID provided by Treblle |\n| config.connect_timeout | 1000 | Timeout in milliseconds when connecting to Treblle |\n| config.send_timeout | 5000 | Timeout in milliseconds when sending data to Treblle |\n| config.keepalive | 5000 | Value in milliseconds that defines how long an idle connection will live before being closed |\n| config.max_callback_time_spent | 750 | Limiter on how much time to send events to Treblle per worker cycle |\n| config.request_max_body_size_limit | 100000 | Maximum request body size in bytes to log |\n| config.response_max_body_size_limit | 100000 | Maximum response body size in bytes to log |\n| config.event_queue_size | 100000 | Maximum number of events to hold in the queue before sending to Treblle |\n| config.debug | false | If set to true, prints internal log messages for debugging integration issues |\n| config.enable_compression | false | If set to true, requests are compressed before sending to Treblle |\n| config.max_retry_count | 1 | Retry count to send the payload to the Treblle API |\n| config.retry_interval | 5 | Retry interval between retries in seconds |\n| config.mask_keywords | | Masking keywords to be used for the entire payload |\n\n**Note**: If you already have Treblle installed, you must update the configuration of the existing instance rather than installing Treblle twice.\n\n## Community\n\nFirst and foremost, **Star and watch this repository** to stay up-to-date.\n\nAlso, follow our [Blog](https://blog.treblle.com), and on [Twitter](https://twitter.com/treblleapi).\n\nYou can chat with the team and other members on [Discord](https://treblle.com/chat) and follow our tutorials and other video material at [YouTube](https://youtube.com/@treblle).\n\n[![Treblle Discord](https://img.shields.io/badge/Treblle%20Discord-Join%20our%20Discord-F3F5FC?labelColor=7289DA\u0026style=for-the-badge\u0026logo=discord\u0026logoColor=F3F5FC\u0026link=https://treblle.com/chat)](https://treblle.com/chat)\n\n[![Treblle YouTube](https://img.shields.io/badge/Treblle%20YouTube-Subscribe%20on%20YouTube-F3F5FC?labelColor=c4302b\u0026style=for-the-badge\u0026logo=YouTube\u0026logoColor=F3F5FC\u0026link=https://youtube.com/@treblle)](https://youtube.com/@treblle)\n\n[![Treblle on Twitter](https://img.shields.io/badge/Treblle%20on%20Twitter-Follow%20Us-F3F5FC?labelColor=1DA1F2\u0026style=for-the-badge\u0026logo=Twitter\u0026logoColor=F3F5FC\u0026link=https://twitter.com/treblleapi)](https://twitter.com/treblleapi)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftreblle%2Ftreblle-kong","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftreblle%2Ftreblle-kong","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftreblle%2Ftreblle-kong/lists"}