# Catalog **Grey Matter Catalog** is one of Grey Matter's core microservices. It provides additional metadata about services to the Grey Matter dashboard. Catalog can be leveraged as an API to develop further visualizations of a service mesh. ## Route: `/summary` ### Method: `GET` Returns an object summarizing all known zones and related metadata. #### Response 200 (application/json) ```javascript { "zones": { "default-zone": { "clusters": { "example": { "clusterName": "example", "zoneName": "default-zone", "name": "Example Service", "version": "1.0", "owner": "Demo", "ownerURL": "https://greymatter.io", "capability": "Demo", "runtime": "GO", "documentation": "/services/example/1.0", "description": "An example service to demonstrate Grey Matter capabilities", "prometheusJob": "example", "minInstances": 1, "maxInstances": 1, "authorized": true, "clusterID": "example", "meshID": "default-zone", "apiEndpoint": "http://greymatter.io/services/example/1.0", "apiSpecEndpoint": "/services/example/1.0", "protocols": [ "mTLS" ], "enableInstanceMetrics": true, "enableHistoricalMetrics": true, "instances": [ { "name": "dca79626b6a99f6783f490556e4a5062", "startTime": 1569247575966 } ], "externalLinks": [ { "name": "Example Service Kibana", "link": "/services/kibana/latest" } ], "metricsTemplate": "", "metricsPort": 8081 }, "fibonacci": { "clusterName": "fibonacci", "zoneName": "default-zone", "name": "Fibonacci", "version": "1.0.0", "owner": "Demo", "ownerURL": "https://greymatter.io", "capability": "Demo", "runtime": "GO", "documentation": "/services/fibonacci/1.0/", "description": "An example service to demonstrate Grey Matter capabilities", "prometheusJob": "fibonacci", "minInstances": 1, "maxInstances": 1, "authorized": true, "clusterID": "fibonacci", "meshID": "default-zone", "enableInstanceMetrics": true, "enableHistoricalMetrics": true, "apiEndpoint": "http://greymatter.io/services/fibonacci/1.0.0", "apiSpecEndpoint": "/services/fibonacci/1.0", "protocols": [ "HTTP" ], "instances": [ { "name": "7795eabdbaf06bb83b2947f74e5d0143", "startTime": 1570807423191 } ], "externalLinks": [ { "name": "Fibonacci Wikipedia", "link": "https://en.wikipedia.org/wiki/Fibonacci_number" } ], "metricsTemplate": "", "metricsPort": 8081 } }, "metadata": { "zoneName": "default-zone", "owners": [ "Demo", "Decipher" ], "capabilities": [ "Demo", "Grey Matter" ], "clusterCount": 22, "clusterStableCount": 17, "clusterWarningCount": 3, "clusterDownCount": 2, "instanceCount": 1 } } }, "metadata": { "zoneCount": 1, "owners": [ "Demo", "Decipher" ], "capabilities": [ "Grey Matter", "Demo" ], "clusterCount": 22, "clusterStableCount": 17, "clusterWarningCount": 3, "clusterDownCount": 2, "instanceCount": 30 }, "meshes": { "default-zone": { "clusters": { "example": { "clusterName": "example", "zoneName": "default-zone", "name": "Example Service", "version": "1.0", "owner": "Demo", "ownerURL": "https://greymatter.io", "capability": "Demo", "runtime": "GO", "documentation": "/services/example/1.0", "description": "An example service to demonstrate Grey Matter capabilities", "prometheusJob": "example", "minInstances": 1, "maxInstances": 1, "authorized": true, "clusterID": "example", "meshID": "default-zone", "apiEndpoint": "http://greymatter.io/services/example/1.0", "apiSpecEndpoint": "/services/example/1.0", "protocols": [ "mTLS" ], "enableInstanceMetrics": true, "enableHistoricalMetrics": true, "instances": [ { "name": "dca79626b6a99f6783f490556e4a5062", "startTime": 1569247575966 } ], "externalLinks": [ { "name": "Example Service Kibana", "link": "/services/kibana/latest" } ], "metricsTemplate": "", "metricsPort": 8081 }, "fibonacci": { "clusterName": "fibonacci", "zoneName": "default-zone", "name": "Fibonacci", "version": "1.0.0", "owner": "Demo", "ownerURL": "https://greymatter.io", "capability": "Demo", "runtime": "GO", "documentation": "/services/fibonacci/1.0/", "description": "An example service to demonstrate Grey Matter capabilities", "prometheusJob": "fibonacci", "minInstances": 1, "maxInstances": 1, "authorized": true, "clusterID": "fibonacci", "meshID": "default-zone", "enableInstanceMetrics": true, "enableHistoricalMetrics": true, "apiEndpoint": "http://greymatter.io/services/fibonacci/1.0.0", "apiSpecEndpoint": "/services/fibonacci/1.0", "protocols": [ "HTTP" ], "instances": [ { "name": "7795eabdbaf06bb83b2947f74e5d0143", "startTime": 1570807423191 } ], "externalLinks": [ { "name": "Fibonacci Wikipedia", "link": "https://en.wikipedia.org/wiki/Fibonacci_number" } ], "metricsTemplate": "", "metricsPort": 8081 } }, "metadata": { "zoneName": "default-zone", "owners": [ "Demo", "Decipher" ], "capabilities": [ "Demo", "Grey Matter" ], "clusterCount": 22, "clusterStableCount": 17, "clusterWarningCount": 3, "clusterDownCount": 2, "instanceCount": 1 } } } } ``` ## Route: `/clusters` ### Method: `GET` Returns a list of service clusters, including running instances and start times. Multiple query parameters may be used: * `status`: accepts `stable`, `warning`, and `down` * `clusterName` * `zoneName` * `name` * `version` * `owner` * `capability` * `prometheusJob` * `authorized` * `enableInstanceMetrics` * `enableHistoricalMetrics` * `businessImpact` * `status` * `protocols` ex: `GET /clusters?name=Example%20Service&owner=Decipher` #### Response 200 (application/json) ```javascript [ { "clusterName": "example-service", "zoneName": "us-east-2", "name": "Example Service", "version": "1.0", "owner": "Decipher", "capability": "Example", "runtime": "GO", "documentation": "/services/example-service/1.0/", "prometheusJob": "example-service", "minInstances": 1, "maxInstances": 1, "authorized": true, "enableInstanceMetrics": true, "enableHistoricalMetrics": false, "metricsPort": 8081, "instances": [ { "name": "cee8014703400366094f6f2be882579d", "startTime": 1548167565788 } ] } ] ``` ### Method: `POST` Adds a new service cluster. ex: `POST /clusters` with the following request body: #### Request (application/json) ```javascript { "clusterName": "example-service", "zoneName": "us-east-2", "name": "Example Service", "version": "1.0", "owner": "Decipher", "capability": "Example", "runtime": "GO", "documentation": "/services/example-service/1.0/", "prometheusJob": "example-service", "minInstances": 1, "maxInstances": 1, "enableInstanceMetrics": true, "enableHistoricalMetrics": false, "metricsPort": 8081 } ``` #### Response 200 (application/json) ```javascript { "clusterName": "example-service", "zoneName": "us-east-2", "name": "Example Service", "version": "1.0", "owner": "Decipher", "capability": "Example", "runtime": "GO", "documentation": "/services/example-service/1.0/", "prometheusJob": "example-service", "minInstances": 1, "maxInstances": 1, "enableInstanceMetrics": true, "enableHistoricalMetrics": false, "metricsPort": 8081 } ``` ## Route: `/clusters/` ### Method: `GET` Returns a list of matching service clusters, including running instances and starttimes. A query parameter may be used to specify a zoneName. ex: `GET /clusters/example-service?zoneName=us-east-2` #### Response 200 (application/json) ```javascript [ { "clusterName": "example-service", "zoneName": "us-east-2", "name": "Example Service", "version": "1.0", "owner": "Decipher", "capability": "Example", "runtime": "GO", "documentation": "/services/example-service/1.0/", "prometheusJob": "example-service", "minInstances": 1, "maxInstances": 1, "authorized": true, "enableInstanceMetrics": true, "enableHistoricalMetrics": false, "metricsPort": 8081, "instances": [ { "name": "cee8014703400366094f6f2be882579d", "startTime": 1548167565788 } ] } ] ``` ### Method: `PUT` Replaces an existing service cluster within a mesh (specified in the request body object). ex: `PUT /clusters/example-service` with the following request body: #### Request (application/json) ```javascript { "clusterName": "example-service", "zoneName": "us-east-2", "name": "My Great Example Service!", "version": "1.0", "owner": "Decipher", "capability": "Exemplar", "runtime": "GO", "documentation": "/services/example-service/1.0/", "prometheusJob": "example-service", "minInstances": 1, "maxInstances": 2, "enableInstanceMetrics": true, "enableHistoricalMetrics": false, "metricsPort": 8081 } ``` #### Response 200 (application/json) ```javascript { "clusterName": "example-service", "zoneName": "us-east-2", "name": "My Great Example Service!", "version": "1.0", "owner": "Decipher", "capability": "Exemplar", "runtime": "GO", "documentation": "/services/example-service/1.0/", "prometheusJob": "example-service", "minInstances": 1, "maxInstances": 2, "enableInstanceMetrics": true, "enableHistoricalMetrics": false, "metricsPort": 8081 } ``` ### Method: `DELETE` Deletes an existing service cluster within a mesh. Note that a zoneName must be specified via query parameter: ex: `DELETE /clusters/example-service?zoneName=us-east-2` #### Response 200 (application/json) ```javascript { "clusterName": "example-service", "zoneName": "us-east-2", "name": "My Great Example Service!", "version": "1.0", "owner": "Decipher", "capability": "Exemplar", "runtime": "GO", "documentation": "/services/example-service/1.0/", "prometheusJob": "example-service", "minInstances": 1, "maxInstances": 2, "enableInstanceMetrics": true, "enableHistoricalMetrics": false, "metricsPort": 8081 } ``` ## Route: `/metrics//` ### Method: `GET` ex: `/metrics/isprime-cluster-1/96cf8008461085dc439e495d7adabd21` #### Response 200 (application/json) ```javascript { "grey-matter-metrics-version": "1.0.0", "Total/requests": 0, "HTTP/requests": 0, "HTTPS/requests": 0, "RPC/requests": 0, "RPC_TLS/requests": 0, "all/requests": 0, "all/routes": "", "all/latency_ms.avg": 0.000000, "all/latency_ms.count": 0, "all/latency_ms.max": 0, "all/latency_ms.min": 0, "all/latency_ms.sum": 0, "all/latency_ms.p50": 0, "all/latency_ms.p90": 0, "all/latency_ms.p95": 0, "all/latency_ms.p99": 0, "all/latency_ms.p9990": 0, "all/latency_ms.p9999": 0, "all/errors.count": 0, "all/in_throughput": 0, "all/out_throughput": 0, "go_metrics/runtime/num_goroutines": 14, "system/start_time": 1548167566942, "system/cpu.pct": 2.275601, "system/cpu_cores": 8, "os": "linux", "os_arch": "amd64", "system/memory/available": 17711955968, "system/memory/used": 8031883264, "system/memory/used_percent": 31.845620, "process/memory/used": 72808696 } ``` ## Route: `/zones` ### Method: `GET` Returns a list of objects related to each known mesh. #### Response 200 (application/json) ```javascript [ { "zoneName": "us-east-1", "requestCluster": "edge", "serverAddress": "discovery.myhost.com:50000", "useTls": false, "caPath": "", "certPath": "", "keyPath": "" }, { "zoneName": "us-east-2", "requestCluster": "edge", "serverAddress": "discovery2.myhost.com:50000", "useTls": false, "caPath": "", "certPath": "", "keyPath": "" } ] ``` ### Method: `POST` Adds a new mesh (i.e. registers a new Control server instance with Catalog). #### Request (application/json) ```javascript { "zoneName": "north-region", "requestCluster": "edge", "serverAddress": "discovery.myhost.com:50000", "useTls": false, "caPath": "", "certPath": "", "keyPath": "" } ``` #### Response 200 (application/json) ```javascript { "zoneName": "north-region", "requestCluster": "edge", "serverAddress": "discovery.myhost.com:50000", "useTls": false, "caPath": "", "certPath": "", "keyPath": "" } ``` ## Route: `/zones/` ### Method: `GET` Returns a metadata object for a specified mesh. ex: `GET /zones/north-region` #### Response 200 (application/json) ```javascript { "zoneName": "north-region", "requestCluster": "edge", "serverAddress": "discovery.myhost.com:50000", "useTls": false, "caPath": "", "certPath": "", "keyPath": "" } ``` ### Method: `DELETE` Deletes an existing mesh AND its service clusters from the Catalog. ex: `DELETE /zones/north-region` #### Response 200 (application/json) ```javascript { "zoneName": "north-region", "requestCluster": "edge", "serverAddress": "discovery.myhost.com:50000", "useTls": false, "caPath": "", "certPath": "", "keyPath": "" } ``` ## Route: `/zones//metadata` ### Method: `GET` Returns a metadata object for a specified mesh. ex: `GET /zones/us-east-2/metadata` #### Response 200 (application/json) ```javascript { "zoneName": "us-east-2", "owners": [ "OpenShift", "Solutions" ], "capabilities": [ "containers", "environments" ], "serviceCount": 4, "stableServiceCount": 3, "warningServiceCount": 1, "downServiceCount": 0, "instanceCount": 4 } ``` ## Route: `/services` (Deprecated) ### Method: `GET` The response contains the entire listing of services that should be present in the mesh, as well as running instances and starttimes. #### Response 200 (application/json) ```javascript [ { "clusterName": "gm-catalog", "zoneName": "us-east", "name": "Grey Matter Catalog", "version": "1.0", "owner": "Decipher", "capability": "gm-catalog", "runtime": "GO", "documentation": "/services/catalog/1.0/", "prometheusJob": "catalog-1.0", "minInstances": 1, "maxInstances": 1, "authorized": true, "enableInstanceMetrics": true, "enableHistoricalMetrics": false, "metricsPort": 8081, "instances": [ { "name": "ebda09996c7f1f7ff2f83dfcdec5b02f", "startTime": 1553863334185 } ] }, { "clusterName": "example-service", "zoneName": "us-west", "name": "Example Service", "version": "1.0", "owner": "Decipher", "capability": "Example", "runtime": "GO", "documentation": "/services/example-service/1.0/", "prometheusJob": "example-service-1.0", "minInstances": 1, "maxInstances": 1, "authorized": true, "enableInstanceMetrics": true, "enableHistoricalMetrics": false, "metricsPort": 8081, "instances": [ { "name": "1d82794e5381fb8fc568195806c3a1b3", "startTime": 1553863266131 } ] } ] ``` ## Route: `/metrics///` (Deprecated) ### Method: `GET` ex: `/metrics/isPrime%20Service/1.0/96cf8008461085dc439e495d7adabd21` #### Response 200 (application/json) ```javascript { "grey-matter-metrics-version": "1.0.0", "Total/requests": 0, "HTTP/requests": 0, "HTTPS/requests": 0, "RPC/requests": 0, "RPC_TLS/requests": 0, "all/requests": 0, "all/routes": "", "all/latency_ms.avg": 0.000000, "all/latency_ms.count": 0, "all/latency_ms.max": 0, "all/latency_ms.min": 0, "all/latency_ms.sum": 0, "all/latency_ms.p50": 0, "all/latency_ms.p90": 0, "all/latency_ms.p95": 0, "all/latency_ms.p99": 0, "all/latency_ms.p9990": 0, "all/latency_ms.p9999": 0, "all/errors.count": 0, "all/in_throughput": 0, "all/out_throughput": 0, "go_metrics/runtime/num_goroutines": 14, "system/start_time": 1548167566942, "system/cpu.pct": 2.275601, "system/cpu_cores": 8, "os": "linux", "os_arch": "amd64", "system/memory/available": 17711955968, "system/memory/used": 8031883264, "system/memory/used_percent": 31.845620, "process/memory/used": 72808696 } ```