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)

{
"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)

[
{
"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)

{
"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)

{
"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/<clusterName>

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)

[
{
"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)

{
"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)

{
"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)

{
"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/<clusterName>/<instance>

Method: GET

ex: /metrics/isprime-cluster-1/96cf8008461085dc439e495d7adabd21

Response 200 (application/json)

{
"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)

[
{
"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)

{
"zoneName": "north-region",
"requestCluster": "edge",
"serverAddress": "discovery.myhost.com:50000",
"useTls": false,
"caPath": "",
"certPath": "",
"keyPath": ""
}

Response 200 (application/json)

{
"zoneName": "north-region",
"requestCluster": "edge",
"serverAddress": "discovery.myhost.com:50000",
"useTls": false,
"caPath": "",
"certPath": "",
"keyPath": ""
}

Route: /zones/<zoneName>

Method: GET

Returns a metadata object for a specified mesh.

ex: GET /zones/north-region

Response 200 (application/json)

{
"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)

{
"zoneName": "north-region",
"requestCluster": "edge",
"serverAddress": "discovery.myhost.com:50000",
"useTls": false,
"caPath": "",
"certPath": "",
"keyPath": ""
}

Route: /zones/<zoneName>/metadata

Method: GET

Returns a metadata object for a specified mesh.

ex: GET /zones/us-east-2/metadata

Response 200 (application/json)

{
"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)

[
{
"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/<service name>/<version>/<instance> (Deprecated)

Method: GET

ex: /metrics/isPrime%20Service/1.0/96cf8008461085dc439e495d7adabd21

Response 200 (application/json)

{
"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
}