From a6ffd4beeaa95363be5b2fc9a4b3bd6e1071c0a8 Mon Sep 17 00:00:00 2001 From: Shubham Sharma Date: Sat, 17 Jun 2023 12:38:59 +0530 Subject: [PATCH 1/9] Update metadata API docs Signed-off-by: Shubham Sharma --- .../content/en/reference/api/metadata_api.md | 186 ++++++++++++------ 1 file changed, 130 insertions(+), 56 deletions(-) diff --git a/daprdocs/content/en/reference/api/metadata_api.md b/daprdocs/content/en/reference/api/metadata_api.md index b0c39c85513..c235a918ae7 100644 --- a/daprdocs/content/en/reference/api/metadata_api.md +++ b/daprdocs/content/en/reference/api/metadata_api.md @@ -6,9 +6,11 @@ description: "Detailed documentation on the Metadata API" weight: 1100 --- -Dapr has a metadata API that returns information about the sidecar allowing runtime discoverability. The metadata endpoint returns a list of the resources (components and HttpEndpoints loaded), the activated actors (if present), and attributes with information attached. +Dapr has a metadata API that returns information about the sidecar allowing runtime discoverability. The metadata endpoint returns the runtime version, a list of the resources (components and HttpEndpoints loaded), the activated actors (if present), subscriptions, app connection details, and attributes with information attached. -## Components +## Metadata API + +### Components Each loaded component provides its name, type and version and also information about supported features in the form of component capabilities. These features are available for the [state store]({{< ref supported-state-stores.md >}}) and [binding]({{< ref supported-bindings.md >}}) component types. The table below shows the component type and the list of capabilities for a given version. This list might grow in future and only represents the capabilities of the loaded components. @@ -17,12 +19,18 @@ Component type | Capabilities State Store | ETAG, TRANSACTION, ACTOR, QUERY_API Binding | INPUT_BINDING, OUTPUT_BINDING -## HTTPEndpoints +### HTTPEndpoints Each loaded `HttpEndpoint` provides a name to easily identify the Dapr resource associated with the runtime. -## Attributes +### Subscriptions +The metadata API returns a list of pubsub subscriptions that the app has registered with the Dapr runtime. This includes the pubsub name, topic, routes, deadletter topic, and the metadata associated with the subscription. + +### App connection details +The metadata API returns information related to Dapr's connection to the app. This includes the app port, protocol, host, max concurrency, along with health check details. + +### Attributes -The metadata API allows you to store additional attribute information in the format of key-value pairs. These are ephemeral in-memory and are not persisted if a sidecar is reloaded. This information should be added at the time of a sidecar creation, for example, after the application has started. +The metadata API allows you to store additional attribute information in the format of key-value pairs. These are ephemeral in-memory and are not persisted if a sidecar is reloaded. This information should be added at the time of a sidecar creation, for example, after the application has started. ## Get the Dapr sidecar information @@ -57,9 +65,13 @@ Code | Description Name | Type | Description ---- | ---- | ----------- id | string | Application ID +runtimeVersion | string | Version of the Dapr runtime actors | [Metadata API Response Registered Actor](#metadataapiresponseactor)[] | A json encoded array of registered actors metadata. extended.attributeName | string | List of custom attributes as key-value pairs, where key is the attribute name. components | [Metadata API Response Component](#metadataapiresponsecomponent)[] | A json encoded array of loaded components metadata. +httpEndpoints | [Metadata API Response HttpEndpoint](#metadataapiresponsehttpendpoint)[] | A json encoded array of loaded HttpEndpoints metadata. +subscriptions | [Metadata API Response Subscription](#metadataapiresponsesubscription)[] | A json encoded array of pubsub subscriptions metadata. +appConnectionProperties| [Metadata API Response AppConnectionProperties](#metadataapiresponseappconnectionproperties) | A json encoded object of app connection properties. **Metadata API Response Registered Actor** @@ -75,7 +87,50 @@ Name | Type | Description name | string | Name of the component. type | string | Component type. version | string | Component version. -capabilities | array | Supported capabilities for this component type and version. +capabilities | array | Supported capabilities for this component type and version. + +**Metadata API Response HttpEndpoint** + +Name | Type | Description +---- | ---- | ----------- +name | string | Name of the HttpEndpoint. + +**Metadata API Response Subscription** + +Name | Type | Description +---- | ---- | ----------- +pubsubname | string | Name of the pubsub. +topic | string | Topic name. +metadata | object | Metadata associated with the subscription. +rules | array of [Metadata API Response Subscription Rules](metadataapiresponsesubscriptionrules) | List of rules associated with the subscription. +deadLetterTopic | string | Dead letter topic name. + +**Metadata API Response Subscription Rules** + +Name | Type | Description +---- | ---- | ----------- +match | string | CEL expression to match the message. +path | string | Path to route the message if the match expression is true. + +**Metadata API Response AppConnectionProperties** + +Name | Type | Description +---- | ---- | ----------- +port | integer| Port on which the app is listening. +protocol | string | Protocol used by the app. +channelAddress| string | Host address on which the app is listening. +maxConcurrency| integer| Maximum number of concurrent requests the app can handle. +health | [Metadata API Response AppConnectionProperties Health](#metadataapiresponseappconnectionpropertieshealth) | Health check details of the app. + +**Metadata API Response AppConnectionProperties Health** + +Name | Type | Description +---- | ---- | ----------- +healthCheckPath | string | Health check path, applicable for HTTP protocol. +healthProbeInterval | string | Time between each health probe, in go duration format. +healthProbeTimeout | string | Timeout for each health probe, in go duration format. +healthThreshold | integer | Max number of failed health probes before the app is considered unhealthy. + ### Examples @@ -87,32 +142,41 @@ curl http://localhost:3500/v1.0/metadata ```json { - "id":"demo-actor", - "actors":[ - { - "type":"DemoActor", - "count":1 - } - ], - "extended": { - "cliPID":"1031040", - "appCommand":"uvicorn --port 3000 demo_actor_service:app", - "daprRuntimeVersion": "1.10.0" + "id": "demo-actor", + "runtimeVersion": "1.12.0", + "actors": [ + { + "type": "DemoActor" + } + ], + "components": [ + { + "name": "pubsub", + "type": "pubsub.redis", + "version": "v1" }, - "components":[ - { - "name":"pubsub", - "type":"pubsub.redis", - "version":"v1", - "capabilities": [""] - }, - { - "name":"statestore", - "type":"state.redis", - "version":"v1", - "capabilities": ["ETAG", "TRANSACTION", "ACTOR", "QUERY_API"] - } - ] + { + "name": "statestore", + "type": "state.redis", + "version": "v1", + "capabilities": [ + "ETAG", + "TRANSACTIONAL", + "ACTOR" + ] + } + ], + "extended": { + "appCommand": "uvicorn --port 3000 demo_actor_service:app", + "appPID": "98121", + "cliPID": "98114", + "daprRuntimeVersion": "1.12.0" + }, + "appConnectionProperties": { + "port": 3000, + "protocol": "http", + "channelAddress": "127.0.0.1" + } } ``` @@ -172,32 +236,42 @@ Get the metadata information to confirm your custom attribute was added: ```json { - "id":"demo-actor", - "actors":[ - { - "type":"DemoActor", - "count":1 - } - ], - "extended": { - "myDemoAttribute": "myDemoAttributeValue", - "cliPID":"1031040", - "appCommand":"uvicorn --port 3000 demo_actor_service:app" + "id": "demo-actor", + "runtimeVersion": "1.12.0", + "actors": [ + { + "type": "DemoActor" + } + ], + "components": [ + { + "name": "pubsub", + "type": "pubsub.redis", + "version": "v1" }, - "components":[ - { - "name":"pubsub", - "type":"pubsub.redis", - "version":"v1", - "capabilities": [""] - }, - { - "name":"statestore", - "type":"state.redis", - "version":"v1", - "capabilities": ["ETAG", "TRANSACTION", "ACTOR", "QUERY_API"] - } - ] + { + "name": "statestore", + "type": "state.redis", + "version": "v1", + "capabilities": [ + "ETAG", + "TRANSACTIONAL", + "ACTOR" + ] + } + ], + "extended": { + "myDemoAttribute": "myDemoAttributeValue", + "appCommand": "uvicorn --port 3000 demo_actor_service:app", + "appPID": "98121", + "cliPID": "98114", + "daprRuntimeVersion": "1.12.0" + }, + "appConnectionProperties": { + "port": 3000, + "protocol": "http", + "channelAddress": "127.0.0.1" + } } ``` From e20f696255b2328ecf11681d6cf583e58e130487 Mon Sep 17 00:00:00 2001 From: Shubham Sharma Date: Sat, 17 Jun 2023 12:49:17 +0530 Subject: [PATCH 2/9] Make type consistent Signed-off-by: Shubham Sharma --- daprdocs/content/en/reference/api/metadata_api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/api/metadata_api.md b/daprdocs/content/en/reference/api/metadata_api.md index c235a918ae7..ed30977036d 100644 --- a/daprdocs/content/en/reference/api/metadata_api.md +++ b/daprdocs/content/en/reference/api/metadata_api.md @@ -102,7 +102,7 @@ Name | Type | Description pubsubname | string | Name of the pubsub. topic | string | Topic name. metadata | object | Metadata associated with the subscription. -rules | array of [Metadata API Response Subscription Rules](metadataapiresponsesubscriptionrules) | List of rules associated with the subscription. +rules | [Metadata API Response Subscription Rules](metadataapiresponsesubscriptionrules)[] | List of rules associated with the subscription. deadLetterTopic | string | Dead letter topic name. **Metadata API Response Subscription Rules** From 455195b3db2b89fc48c8c67cf86bad4a8dca2499 Mon Sep 17 00:00:00 2001 From: Shubham Sharma Date: Mon, 19 Jun 2023 11:37:46 +0530 Subject: [PATCH 3/9] Add docs for enabledFeatures Signed-off-by: Shubham Sharma --- daprdocs/content/en/reference/api/metadata_api.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/api/metadata_api.md b/daprdocs/content/en/reference/api/metadata_api.md index ed30977036d..b7f921a239a 100644 --- a/daprdocs/content/en/reference/api/metadata_api.md +++ b/daprdocs/content/en/reference/api/metadata_api.md @@ -6,7 +6,7 @@ description: "Detailed documentation on the Metadata API" weight: 1100 --- -Dapr has a metadata API that returns information about the sidecar allowing runtime discoverability. The metadata endpoint returns the runtime version, a list of the resources (components and HttpEndpoints loaded), the activated actors (if present), subscriptions, app connection details, and attributes with information attached. +Dapr has a metadata API that returns information about the sidecar allowing runtime discoverability. The metadata endpoint returns the runtime version, a list of the resources (components and HttpEndpoints loaded), the activated actors (if present), subscriptions, enabled features, app connection details, and attributes with information attached. ## Metadata API @@ -25,6 +25,9 @@ Each loaded `HttpEndpoint` provides a name to easily identify the Dapr resource ### Subscriptions The metadata API returns a list of pubsub subscriptions that the app has registered with the Dapr runtime. This includes the pubsub name, topic, routes, deadletter topic, and the metadata associated with the subscription. +### Enabled features +A list of features enabled during build time, this does not include the features from Configuration spec. + ### App connection details The metadata API returns information related to Dapr's connection to the app. This includes the app port, protocol, host, max concurrency, along with health check details. @@ -166,6 +169,9 @@ curl http://localhost:3500/v1.0/metadata ] } ], + "enabledFeatures": [ + "ServiceInvocationStreaming" + ], "extended": { "appCommand": "uvicorn --port 3000 demo_actor_service:app", "appPID": "98121", @@ -260,6 +266,9 @@ Get the metadata information to confirm your custom attribute was added: ] } ], + "enabledFeatures": [ + "ServiceInvocationStreaming" + ], "extended": { "myDemoAttribute": "myDemoAttributeValue", "appCommand": "uvicorn --port 3000 demo_actor_service:app", From bf17f2d6cdd63315ef462f4ad41a8451d60c7037 Mon Sep 17 00:00:00 2001 From: Shubham Sharma Date: Mon, 19 Jun 2023 12:23:19 +0530 Subject: [PATCH 4/9] Update docs Signed-off-by: Shubham Sharma --- daprdocs/content/en/reference/api/metadata_api.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/daprdocs/content/en/reference/api/metadata_api.md b/daprdocs/content/en/reference/api/metadata_api.md index b7f921a239a..4bc2a5406f3 100644 --- a/daprdocs/content/en/reference/api/metadata_api.md +++ b/daprdocs/content/en/reference/api/metadata_api.md @@ -26,7 +26,7 @@ Each loaded `HttpEndpoint` provides a name to easily identify the Dapr resource The metadata API returns a list of pubsub subscriptions that the app has registered with the Dapr runtime. This includes the pubsub name, topic, routes, deadletter topic, and the metadata associated with the subscription. ### Enabled features -A list of features enabled during build time, this does not include the features from Configuration spec. +A list of features enabled via Configuration spec (including build-time overrides). ### App connection details The metadata API returns information related to Dapr's connection to the app. This includes the app port, protocol, host, max concurrency, along with health check details. @@ -147,6 +147,9 @@ curl http://localhost:3500/v1.0/metadata { "id": "demo-actor", "runtimeVersion": "1.12.0", + "enabledFeatures": [ + "ServiceInvocationStreaming" + ], "actors": [ { "type": "DemoActor" @@ -169,9 +172,6 @@ curl http://localhost:3500/v1.0/metadata ] } ], - "enabledFeatures": [ - "ServiceInvocationStreaming" - ], "extended": { "appCommand": "uvicorn --port 3000 demo_actor_service:app", "appPID": "98121", @@ -244,6 +244,9 @@ Get the metadata information to confirm your custom attribute was added: { "id": "demo-actor", "runtimeVersion": "1.12.0", + "enabledFeatures": [ + "ServiceInvocationStreaming" + ], "actors": [ { "type": "DemoActor" @@ -266,9 +269,6 @@ Get the metadata information to confirm your custom attribute was added: ] } ], - "enabledFeatures": [ - "ServiceInvocationStreaming" - ], "extended": { "myDemoAttribute": "myDemoAttributeValue", "appCommand": "uvicorn --port 3000 demo_actor_service:app", From b9e3038de300de46c4ee69a922c1090a77cfd085 Mon Sep 17 00:00:00 2001 From: Shubham Sharma Date: Mon, 19 Jun 2023 21:49:29 +0530 Subject: [PATCH 5/9] Update daprdocs/content/en/reference/api/metadata_api.md Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Signed-off-by: Shubham Sharma --- daprdocs/content/en/reference/api/metadata_api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/api/metadata_api.md b/daprdocs/content/en/reference/api/metadata_api.md index 4bc2a5406f3..e011959a595 100644 --- a/daprdocs/content/en/reference/api/metadata_api.md +++ b/daprdocs/content/en/reference/api/metadata_api.md @@ -23,7 +23,7 @@ Binding | INPUT_BINDING, OUTPUT_BINDING Each loaded `HttpEndpoint` provides a name to easily identify the Dapr resource associated with the runtime. ### Subscriptions -The metadata API returns a list of pubsub subscriptions that the app has registered with the Dapr runtime. This includes the pubsub name, topic, routes, deadletter topic, and the metadata associated with the subscription. +The metadata API returns a list of pub/sub subscriptions that the app has registered with the Dapr runtime. This includes the pub/sub name, topic, routes, dead letter topic, and the metadata associated with the subscription. ### Enabled features A list of features enabled via Configuration spec (including build-time overrides). From ff1281b67dc1b32700b822fa3fbffce542c7928f Mon Sep 17 00:00:00 2001 From: Shubham Sharma Date: Mon, 19 Jun 2023 21:49:39 +0530 Subject: [PATCH 6/9] Update daprdocs/content/en/reference/api/metadata_api.md Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Signed-off-by: Shubham Sharma --- daprdocs/content/en/reference/api/metadata_api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/api/metadata_api.md b/daprdocs/content/en/reference/api/metadata_api.md index e011959a595..0baaab95a73 100644 --- a/daprdocs/content/en/reference/api/metadata_api.md +++ b/daprdocs/content/en/reference/api/metadata_api.md @@ -33,7 +33,7 @@ The metadata API returns information related to Dapr's connection to the app. Th ### Attributes -The metadata API allows you to store additional attribute information in the format of key-value pairs. These are ephemeral in-memory and are not persisted if a sidecar is reloaded. This information should be added at the time of a sidecar creation, for example, after the application has started. +The metadata API allows you to store additional attribute information in the format of key-value pairs. These are ephemeral in-memory and are not persisted if a sidecar is reloaded. This information should be added at the time of a sidecar creation (for example, after the application has started). ## Get the Dapr sidecar information From a6998f2b8dc132bff239c544402c6576661c6969 Mon Sep 17 00:00:00 2001 From: Shubham Sharma Date: Mon, 19 Jun 2023 21:49:45 +0530 Subject: [PATCH 7/9] Update daprdocs/content/en/reference/api/metadata_api.md Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Signed-off-by: Shubham Sharma --- daprdocs/content/en/reference/api/metadata_api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/api/metadata_api.md b/daprdocs/content/en/reference/api/metadata_api.md index 0baaab95a73..c7d22e4056c 100644 --- a/daprdocs/content/en/reference/api/metadata_api.md +++ b/daprdocs/content/en/reference/api/metadata_api.md @@ -73,7 +73,7 @@ actors | [Metadata API Response Registered Actor](#metadataapire extended.attributeName | string | List of custom attributes as key-value pairs, where key is the attribute name. components | [Metadata API Response Component](#metadataapiresponsecomponent)[] | A json encoded array of loaded components metadata. httpEndpoints | [Metadata API Response HttpEndpoint](#metadataapiresponsehttpendpoint)[] | A json encoded array of loaded HttpEndpoints metadata. -subscriptions | [Metadata API Response Subscription](#metadataapiresponsesubscription)[] | A json encoded array of pubsub subscriptions metadata. +subscriptions | [Metadata API Response Subscription](#metadataapiresponsesubscription)[] | A json encoded array of pub/sub subscriptions metadata. appConnectionProperties| [Metadata API Response AppConnectionProperties](#metadataapiresponseappconnectionproperties) | A json encoded object of app connection properties. **Metadata API Response Registered Actor** From 1923124de55ce1741f1b2637e51303b2ef335eba Mon Sep 17 00:00:00 2001 From: Shubham Sharma Date: Mon, 19 Jun 2023 21:49:50 +0530 Subject: [PATCH 8/9] Update daprdocs/content/en/reference/api/metadata_api.md Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Signed-off-by: Shubham Sharma --- daprdocs/content/en/reference/api/metadata_api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/api/metadata_api.md b/daprdocs/content/en/reference/api/metadata_api.md index c7d22e4056c..cb11406246d 100644 --- a/daprdocs/content/en/reference/api/metadata_api.md +++ b/daprdocs/content/en/reference/api/metadata_api.md @@ -102,7 +102,7 @@ name | string | Name of the HttpEndpoint. Name | Type | Description ---- | ---- | ----------- -pubsubname | string | Name of the pubsub. +pubsubname | string | Name of the pub/sub. topic | string | Topic name. metadata | object | Metadata associated with the subscription. rules | [Metadata API Response Subscription Rules](metadataapiresponsesubscriptionrules)[] | List of rules associated with the subscription. From 95e976d57167dbd1412094212312acf13aa63d0b Mon Sep 17 00:00:00 2001 From: Shubham Sharma Date: Tue, 20 Jun 2023 09:29:40 +0530 Subject: [PATCH 9/9] Update daprdocs/content/en/reference/api/metadata_api.md Co-authored-by: Mark Fussell Signed-off-by: Shubham Sharma --- daprdocs/content/en/reference/api/metadata_api.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/api/metadata_api.md b/daprdocs/content/en/reference/api/metadata_api.md index cb11406246d..737e98671aa 100644 --- a/daprdocs/content/en/reference/api/metadata_api.md +++ b/daprdocs/content/en/reference/api/metadata_api.md @@ -6,7 +6,13 @@ description: "Detailed documentation on the Metadata API" weight: 1100 --- -Dapr has a metadata API that returns information about the sidecar allowing runtime discoverability. The metadata endpoint returns the runtime version, a list of the resources (components and HttpEndpoints loaded), the activated actors (if present), subscriptions, enabled features, app connection details, and attributes with information attached. +Dapr has a metadata API that returns information about the sidecar allowing runtime discoverability. The metadata endpoint returns the following information. +- Runtime version +- List of the loaded resources (`components`, `subscriptions` and `HttpEndpoints`) +- Registered actor types +- Features enabled +- Application connection details +- Custom, ephemeral attributes with information. ## Metadata API