Datawire MDK

mdk

class mdk.LoggedMessageId(traceId, causalLevel, environment, environmentFallback)

Information about the message that was just logged.

mdk_LoggedMessageId_ref = None

quark_List_quark_int__ref = None

class mdk.MDK

The MDK API consists of two interfaces: MDK and Session. The MDK interface holds globally scoped APIs and state associated with the microservice. The Session interface holds locally scoped APIs and state. A Session must be used sequentially.

The MDK instance is responsible for communicating with foundational services like discovery and tracing.

There will typically be one MDK instance for the entire process, and one instance of the Session object per thread/channel/request depending on how the MDK is integrated and used within the application framework of choice.

A note on versions: service versions indicate API compatibility, not releases of the underlying code. They should be in the form MAJOR.MINOR, e.g. ‘2.11’. Major versions indicates incompatibility: ‘1.0’ is incompatible with ‘2.11’. Minor versions indicate backwards compatibility with new features: a client that wants version ‘1.1’ can talk to version ‘1.1’ and ‘1.2’ but not to version ‘1.0’.

CONTEXT_HEADER = u'X-MDK-Context'

derive(encodedContext)

Create a new Session. The given encoded distributed session’s properties will be used to configure the new Session, e.g. overrides will be preserved. However, because this is a new Session the timeout will not be copied from the encoded session.

This is intended for use for encoded context received via a broadcast medium (pub/sub, message queues with multiple readers, etc.). If you know only you received the encoded context, e.g. you’re coding a server that receives the context from a HTTP request, you should join() instead.

join(encodedContext)

Create a new Session and join it to an existing distributed sesion.

This should only ever be done once per an encoded context. That means you should only use it for RPC or similar one-off calls. If you received the encoded context via a broadcast medium (pub/sub, message queues with multiple readers, etc.) you should use childSession() instead.

mdk_MDK_ref = None

register(service, version, address)

Registers a service endpoint with the discovery system. This can be called at any point, however registered endpoints will not be advertised to the discovery system until the MDK is started.

session()

Creates a new Session. A Session created in this way will result in a new distributed trace. This should therefore be used primarily by edge services. Intermediary and foundational services should make use of join(encodedContext) in order to preserve distributed traces.

setDefaultDeadline(seconds)

Set the default timeout for MDK sessions.

This is the maximum timeout; if a joined session has a lower timeout that will be used.

setDefaultTimeout(seconds)

DEPRECATED, use setDefaultDeadline().

start()

Start the MDK. An MDK instance will not communicate with foundational services unless it is started.

stop()

Stop the MDK. When the MDK stops unregisters any service endpoints from the discovery system. This should always be done prior to process exit in order to propogate node shutdowns in realtime rather than waiting for heartbeats to detect node departures.

class mdk.MDKImpl(runtime)

CONTEXT_HEADER = u'X-MDK-Context'

derive(encodedContext)

getDiscoveryFactory(env)

Choose DiscoverySource based on environment variables.

getFailurePolicy(runtime)

Choose FailurePolicy based on environment variables.

getWSClient(runtime)

Get a WSClient, unless env variables suggest the user doesn’t want one.

join(encodedContext)

mdk_MDKImpl_ref = None

quark_Map_quark_String_quark_Object__ref = None

register(service, version, address)

session()

setDefaultDeadline(seconds)

setDefaultTimeout(seconds)

start()

stop()

class mdk.Session

A session provides a lightweight sequential context that a microservice can use in the context of any application framework in order to manage its interactions with other microservices. It provides simple APIs for service resolution, distributed tracing, and circuit breakers.

A microservices architecture enables small self contained units of business logic to be implemented by separate teams working on isolated services based on the languages and frameworks best suited for their problem domain.

Any given microservice will contain sequential business logic implemented in a variety of ways depending on the application framework chosen. For example it may be a long running thread, a simple blocking request handler, or a chained series of reactive handlers in an async environment.

For the most part this business logic can be implemented exactly as prescribed by the application framework of choice, however in a microservices architecture, some special care needs to be taken when this business logic interacts with other microservices.

Because microservices are updated with much higher frequency than normal web applications, the interactions between them form key points that require extra care beyond normal web interactions in order to avoid creating a system that is both extremely fragile, unreliable, and opaque.

Realtime service resolution, distributed tracing, and resilience heuristics such as circuit breakers provide the foundational behavior required at these interaction points. These capabilites must be combined with the defensive coding practice of intelligent fallback behavior when remote services are unavailable or misbehaving, in order to build a robust microservice application.

Because of this, a session is expected to be created and made available to all business logic within a given microservice, e.g. on a per request basis, as a thread local, part of a context object, etc depending on the application framework of choice.

critical(category, text)

Record a log entry at the CRITICAL logging level.

debug(category, text)

Record a log entry at the DEBUG logging level.

error(category, text)

Record a log entry at the ERROR logging level.

externalize()

Returns an externalized representation of the distributed session.

fail_interaction(message)

Record an interaction as failed.

This will update circuit breaker state for the remote nodes, as well as reporting all nodes involved to the tracing system.

finish_interaction()

Finish an interaction.

This marks an interaction as completed.

getEnvironment()

Return the session’s Environment.

getProperty(property)

Return the value of a property from the distributed session.

getRemainingTime()

Return how many seconds until the session ought to end.

This will only be accurate across multiple servers insofar as their clocks are in sync.

If a timeout has not been set the result will be null.

hasProperty(property)

Return whether the distributed session has a property.

info(category, text)

Record a log entry at the INFO logging level.

inject()

Grabs the encoded context.

interact(callable)

This is a convenience API that will perform start_interaction() followed by callable(ssn) followed by finish_interaction().

mdk_Session_ref = None

resolve(service, version)

Locate a compatible service instance.

Uses a minimum of 10 seconds and the timeout set on the session.

resolve_async(service, version)

Locate a compatible service instance asynchronously. The result is returned as a promise.

resolve_until(service, version, timeout)

Locate a compatible service instance with a non-default timeout.

route(service, version, target, targetVersion)

EXPERIMENTAL; requires MDK_EXPERIMENTAL=1 environment variable to function.

Override service resolution for the current distributed session. All attempts to resolve service, version will be replaced with an attempt to resolve target, targetVersion. This effect will be propogated to any downstream services involved in the distributed session.

setDeadline(seconds)

Set how many seconds the session is expected to live from this point.

If a timeout has previously been set the new timeout will only be used if it is lower than the existing timeout.

The MDK will not enforce the timeout. Rather, it provides the information to any process or server in the same session (even if they are on different machines). By passing this timeout to blocking APIs you can ensure timeouts are enforced across a whole distributed session.

setProperty(property, value)

Set a property on the distributed session.

The key should be prefixed with a namespace so that it doesn’t conflict with built-in properties, e.g. ‘examplenamespace:myproperty’ instead of ‘myproperty’.

The value should be JSON serializable.

setTimeout(seconds)

DEPRECATED, use setDeadline().

start_interaction()

Start an interaction with a remote service.

The session tracks any nodes resolved during an interactin with a remote service.

The service resolution API permits a compatible instance of the service to be located. In addition, it tracks which exact instances are in use during any interaction. Should the interaction fail, circuit breaker state is updated for those nodes, and all involved instances involved are reported to the tracing services.

This permits realtime reporting of integration issues when services are updated, and also allows circuit breakers to mitigate the impact of any such issues.

trace(level)

EXPERIMENTAL: Set the logging level for the session.

warn(category, text)

Record a log entry at the WARN logging level.

class mdk.SessionImpl(mdk, encodedContext, localEnvironment)

critical(category, text)

debug(category, text)

error(category, text)

externalize()

fail_interaction(message)

finish_interaction()

getEnvironment()

getProperty(property)

getRemainingTime()

hasProperty(property)

info(category, text)

inject()

interact(cmd)

mdk_SessionImpl_ref = None

quark_List_mdk_discovery_Node__ref = None

quark_List_mdk_metrics_InteractionEvent__ref = None

quark_List_quark_List_mdk_discovery_Node___ref = None

quark_List_quark_Map_quark_String_quark_String___ref = None

quark_List_quark_String__ref = None

quark_Map_quark_String_quark_List_quark_Map_quark_String_quark_String____ref = None

quark_Map_quark_String_quark_String__ref = None

quark_Map_quark_String_quark_int__ref = None

resolve(service, version)

resolve_async(service, version)

resolve_until(service, version, timeout)

route(service, version, target, targetVersion)

setDeadline(timeout)

setProperty(property, value)

setTimeout(timeout)

start_interaction()

trace(level)

warn(category, text)

mdk.init()

Create an unstarted instance of the MDK.

mdk.start()

Create a started instance of the MDK. This is equivalent to calling init() followed by start() on the resulting instance.

Indices and tables

• Index
• Module Index
• Search Page