Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add new properties to the metadata API #3562

Merged
merged 9 commits into from
Jun 21, 2023
Merged

Add new properties to the metadata API #3562

Changes from 3 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
a6ffd4b
Update metadata API docs
shubham1172 Jun 17, 2023
e20f696
Make type consistent
shubham1172 Jun 17, 2023
455195b
Add docs for enabledFeatures
shubham1172 Jun 19, 2023
bf17f2d
Update docs
shubham1172 Jun 19, 2023
b9e3038
Update daprdocs/content/en/reference/api/metadata_api.md
shubham1172 Jun 19, 2023
ff1281b
Update daprdocs/content/en/reference/api/metadata_api.md
shubham1172 Jun 19, 2023
a6998f2
Update daprdocs/content/en/reference/api/metadata_api.md
shubham1172 Jun 19, 2023
1923124
Update daprdocs/content/en/reference/api/metadata_api.md
shubham1172 Jun 19, 2023
95e976d
Update daprdocs/content/en/reference/api/metadata_api.md
shubham1172 Jun 20, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
195 changes: 139 additions & 56 deletions daprdocs/content/en/reference/api/metadata_api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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, enabled features, app connection details, and attributes with information attached.
shubham1172 marked this conversation as resolved.
Show resolved Hide resolved

## 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.

Expand All @@ -17,12 +19,21 @@ 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.
shubham1172 marked this conversation as resolved.
Show resolved Hide resolved

### Enabled features
A list of features enabled during build time, this does not include the features from Configuration spec.
shubham1172 marked this conversation as resolved.
Show resolved Hide resolved

### 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.

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.
### 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.
shubham1172 marked this conversation as resolved.
Show resolved Hide resolved

## Get the Dapr sidecar information

Expand Down Expand Up @@ -57,9 +68,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.
shubham1172 marked this conversation as resolved.
Show resolved Hide resolved
appConnectionProperties| [Metadata API Response AppConnectionProperties](#metadataapiresponseappconnectionproperties) | A json encoded object of app connection properties.

<a id="metadataapiresponseactor"></a>**Metadata API Response Registered Actor**

Expand All @@ -75,7 +90,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.

<a id="metadataapiresponsehttpendpoint"></a>**Metadata API Response HttpEndpoint**

Name | Type | Description
---- | ---- | -----------
name | string | Name of the HttpEndpoint.

<a id="metadataapiresponsesubscription"></a>**Metadata API Response Subscription**

Name | Type | Description
---- | ---- | -----------
pubsubname | string | Name of the pubsub.
shubham1172 marked this conversation as resolved.
Show resolved Hide resolved
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.
deadLetterTopic | string | Dead letter topic name.

<a id="metadataapiresponsesubscriptionrules"></a>**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.

<a id="metadataapiresponseappconnectionproperties"></a>**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.

<a id="metadataapiresponseappconnectionpropertieshealth"></a>**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

Expand All @@ -87,32 +145,44 @@ 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"
]
}
],
"enabledFeatures": [
"ServiceInvocationStreaming"
],
"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"
}
}
```

Expand Down Expand Up @@ -172,32 +242,45 @@ 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"
]
}
],
"enabledFeatures": [
"ServiceInvocationStreaming"
],
"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"
}
}
```

Expand Down
Loading