Packages

  • package root
    Definition Classes
    root
  • package com
    Definition Classes
    root
  • package twitter

    Start with com.twitter.finagle.

    Definition Classes
    com
  • package finagle

    Finagle is an extensible RPC system.

    Finagle is an extensible RPC system.

    Services are represented by class com.twitter.finagle.Service. Clients make use of com.twitter.finagle.Service objects while servers implement them.

    Finagle contains a number of protocol implementations; each of these implement Client and/or com.twitter.finagle.Server. For example, Finagle's HTTP implementation, com.twitter.finagle.Http (in package finagle-http), exposes both.

    Thus a simple HTTP server is built like this:

    import com.twitter.finagle.{Http, Service}
    import com.twitter.finagle.http.{Request, Response}
    import com.twitter.util.{Await, Future}
    
    val service = new Service[Request, Response] {
      def apply(req: Request): Future[Response] =
        Future.value(Response())
    }
    val server = Http.server.serve(":8080", service)
    Await.ready(server)

    We first define a service to which requests are dispatched. In this case, the service returns immediately with a HTTP 200 OK response, and with no content.

    This service is then served via the Http protocol on TCP port 8080. Finally we wait for the server to stop serving.

    We can now query our web server:

    % curl -D - localhost:8080
    HTTP/1.1 200 OK

    Building an HTTP client is also simple. (Note that type annotations are added for illustration.)

    import com.twitter.finagle.{Http, Service}
    import com.twitter.finagle.http.{Request, Response}
    import com.twitter.util.{Future, Return, Throw}
    
    val client: Service[Request, Response] = Http.client.newService("localhost:8080")
    val f: Future[Response] = client(Request()).respond {
      case Return(rep) =>
        printf("Got HTTP response %s\n", rep)
      case Throw(exc) =>
        printf("Got error %s\n", exc)
    }

    Http.client.newService("localhost:8080") constructs a new com.twitter.finagle.Service instance connected to localhost TCP port 8080. We then issue a HTTP/1.1 GET request to URI "/". The service returns a com.twitter.util.Future representing the result of the operation. We listen to this future, printing an appropriate message when the response arrives.

    The Finagle homepage contains useful documentation and resources for using Finagle.

    Definition Classes
    twitter
  • package addr
    Definition Classes
    finagle
  • package builder
    Definition Classes
    finagle
  • package client
    Definition Classes
    finagle
  • package context
    Definition Classes
    finagle
  • package core
    Definition Classes
    finagle
  • package dispatch
    Definition Classes
    finagle
  • package exp

    Package exp contains experimental code.

    Package exp contains experimental code. This can be removed or stabilized (moved elsewhere) at any time.

    Definition Classes
    finagle
  • package factory
    Definition Classes
    finagle
  • package filter
    Definition Classes
    finagle
  • package http
    Definition Classes
    finagle
  • package http2
    Definition Classes
    finagle
  • package liveness
    Definition Classes
    finagle
  • package loadbalancer

    This package implements client side load balancing algorithms.

    This package implements client side load balancing algorithms.

    As an end-user, see the Balancers API to create instances which can be used to configure a Finagle client with various load balancing strategies.

    As an implementor, each algorithm gets its own subdirectory and is exposed via the Balancers object. Several convenient traits are provided which factor out common behavior and can be mixed in (i.e. Balancer, DistributorT, NodeT, and Updating).

    Definition Classes
    finagle
  • package logging
    Definition Classes
    finagle
  • package memcached
    Definition Classes
    finagle
  • package mux

    Package mux implements a generic RPC multiplexer with a rich protocol.

    Package mux implements a generic RPC multiplexer with a rich protocol. Mux is itself encoding independent, so it is meant to use as the transport for other RPC systems (eg. thrift). In OSI terminology, it is a pure session layer.

    In the below description, all numeric values are unsigned and in big-endian byte order. The schema size:4 body:10 defines the field size to be 4 bytes, followed by 10 bytes of the field body. The schema key~4 defines the field key to be defined by 4 bytes interpreted as the size of the field, followed by that many bytes comprising the field itself--it is shorthand for keysize:4 key:keysize. Groups are denoted by parenthesis; * denotes repetition of the previous schema 0 or more times, while {n} indicates repetition exactly n times. Unspecified sizes consume the rest of the frame: they may be specified only as the last field in the message.

    All strings in Mux are Utf-8 encoded, and are never null-terminated.

    Message framing

    Messages in mux are framed with a 4-byte big-endian size header, followed by 1 byte describing the message type and a 3-byte tag; or, diagrammatically: size:4 type:1 tag:3. The remainder of the frame (size-4 bytes) contains the body. Its format depends on the message type, documented below.

    Tag 0 designates a "marker" T message that expects no reply. Some messages may be split into an ordered sequence of fragments. Tag MSB=0 denotes the last message in such a sequence, making the tag namespace 23 bits. The tag is otherwise arbitrary, and is chosen by the sender of the T message.

    Currently, only Tdispatch and Rdispatch messages may be split into an ordered sequence of fragments. TdispatchError message ends a Tdispatch sequence and an Rerr ends an Rdispatch sequence.

    Message types, interpreted as a two's complement, 1-byte integer are numbered as follows: positive numbers are T-messages; their negative complement is the corresponding R message. T-messages greater than 63 (correspondingly R-messages smaller than -63) are session messages. The message number -128 is reserved for Rerr. All other messages are application messages. Middle boxes may forward application messages indiscriminately. Because of an early implementation bug, two aliases exist: 127 is Rerr, and -62 is Tdiscarded.

    The protocol is full duplex: both the server and client may send T messages initiating an exchange.

    Exchanges

    Messages are designated as "T messages" or "R messages", T and R being stand-ins for transmit and receive. A T message initiates an exchange and is assigned a free tag by the sender. A reply is either an R message of the same type (Rx replies to Tx for some x), or an Rerr, indicating a session layer error. R messages are matched to their T messages by tag, and the reply concludes the exchange and frees the tag for future use. Implementations should reuse small tag numbers.

    Messages

    size:4 Tinit:1 tag:3 version:2 (key~4 value~4)* reinitializes a session. Clients typically send this at the beginning of the session. When doing so, the sender may issue no more T messages until the corresponding size:4 Rinit:1 tag:3 version:2 (key~4 value~4)* has been received. After the Rinit was received, all connection state has been reset (outstanding tags are invalidated) and the stream is resumed according to the newly negotiated parameters. Prior to the first Tinit, the session operates at version 1. Rinit's version field is the accepted version of the session (which may be lower than the one requested by Tinit).

    size:4 Treq:1 tag:3 n:1 (key:1 value~1){n} body: initiates the request described by its body. The request body is delivered to the application. The request header contains a number of key-value pairs that describe request metadata.

    Keys for Treq messages are as follows:

    1. traceid: a 24-byte value describing the full Dapper trace id assigned by the client. The value's format is spanid:8 parentid:8 traceid:8.

    2. traceflag: a bitmask describing trace flags. Currently, the only defined flag is bit 0 which enables "debug mode", asking the server to force trace sampling.

    size:4 Tdispatch:1 tag:3 nctx:2 (ckey~2 cval~2){nc} dst~2 nd:2 (from~2 to~2){nd} body: implements destination dispatch. Tdispatch messages carry a set of keyed request contexts, followed by a logical destination encoded as a UTF-8 string. A delegation table follows describing rewrite rules that apply to this request.

    size:4 Rreq:1 tag:3 status:1 body: replies to a request. Status codes are as follows: 0=OK; the body contains the reply. 1=ERROR; the body contains a string describing the error. 2=NACK; a negative acknowledgment, the body contains a string describing the reason.

    size:4 Rdispatch:1 tag:3 status:1 nctx:2 (key~2 value~2){nctx} body: replies to a Tdispatch request. Status codes are as in Rreq. Replies can include request contexts. MuxFailure flags are currently sent via Rdispatch contexts under the "MuxFailure" key. See the MuxFailure flags section below.

    size:4 Rerr:1 tag:3 why: indicates that the corresponding T message produced an error. Rerr is specifically for server errors: the server failed to interpret or act on the message. The body carries a string describing the error.

    size:4 Tdrain:1 tag:3 is a request sent by the server telling the client to stop sending new requests. A client acknowledges this with an Rdrain message.

    size:4 Tping:1 tag:3 is sent by either party to check the liveness of its peer; these should be responded to immediately with a Rping message.

    size:4 Tdiscarded:1 tag:3 discard_tag:3 why: is a marker message and therefore has a tag value of 0. discard_tag indicates the tag of the Tdispatch to be discarded by the client. This can be used as a hint for early termination. Why is a string describing why the request was discarded. Note that it does *not* free the server from the obligation of replying to the original Treq.

    size:4 Tlease:1 tag:3 unit:1 howmuch:8 is a marker message indicating that a lease has been issued for howmuch units. As a marker message, its tag value must be 0. Unit '0' is reserved for duration in milliseconds. Whenever a lease has not been issued, a client can assume it holds an indefinite lease. Adhering to the lease is optional, but the server may reject requests or provide degraded service should the lease expire. This is used by servers to implement features like garbage collection avoidance.

    MuxFailure Flags

    Failure flags are read and written as an 8 byte integer. Unrecognized flags will be ignored silently, but should all be considered reserved for future use.

    Flag Value Meaning Restartable 1 << 0 Request is safe to re-issue Rejected 1 << 1 Request was rejected/Nacked by the server NonRetryable 1 << 2 Request should not be retried

    Security

    TLS is supported via three mechanisms: - Explicit and exclusive TLS. This pathway involves requiring the establishment of TLS immediately after establishing the socket connection. This is configured by adding TLS configuration to the client or server and not configuring opportunistic TLS or TLS snooping (see below).

    - Negotiated Opportunistic TLS. This pathway involves starting the connection as cleartext and the client and server subsequently negotiate a TLS level via the handshake. Based on that handshake the connection is either left as cleartext or upgraded to TLS. This is configured by adding TLS configuration and also configuring an opportunistic TLS level but not configuring TLS snooping.

    In this pathway there are three configuration options:

    • Off signals that TLS is not supported by this peer
    • Desired signals that TLS is preferred but not required by this peer
    • Required signals that this peer will only allow the session to continue over TLS

    - TLS snooping. This pathway allows a server to use TLS either by performing a TLS handshake immediately after the socket is established or by starting the session as cleartext or using the negotiated pathway described above. If the session is started as a TLS session the headers that drive the opportunistic TLS pathway are ignored.

    Note that the server may still require TLS but leaves the option to start TLS immediately after establishing the socket or starting cleartext and requiring TLS via the opportunistic TLS pathway described above.

    Definition Classes
    finagle
  • package mysql
    Definition Classes
    finagle
  • package namer
    Definition Classes
    finagle
  • package naming
    Definition Classes
    finagle
  • package netty4

    Package netty4 implements the bottom finagle primitives: com.twitter.finagle.Server and a client transport in terms of the netty4 event loop.

    Package netty4 implements the bottom finagle primitives: com.twitter.finagle.Server and a client transport in terms of the netty4 event loop.

    Definition Classes
    finagle
  • package offload
    Definition Classes
    finagle
  • package param

    Defines common com.twitter.finagle.Stack.Param's shared between finagle clients and servers.

    Defines common com.twitter.finagle.Stack.Param's shared between finagle clients and servers.

    Definition Classes
    finagle
  • package partitioning
    Definition Classes
    finagle
  • package pool
    Definition Classes
    finagle
  • package postgresql
    Definition Classes
    finagle
  • package pushsession
    Definition Classes
    finagle
  • package redis
    Definition Classes
    finagle
  • package scribe
    Definition Classes
    finagle
  • package server
    Definition Classes
    finagle
  • package serverset2
    Definition Classes
    finagle
  • package service
    Definition Classes
    finagle
  • package ssl
    Definition Classes
    finagle
  • package stats
    Definition Classes
    finagle
  • package thrift

    Please use the new interface, com.twitter.finagle.Thrift, for constructing Thrift clients and servers.

    Deprecation

    Please use the new interface, com.twitter.finagle.Thrift, for constructing Thrift clients and servers.

    Thrift codecs

    We provide client and server protocol support for the framed protocol. The public implementations are defined on the Thrift object:

    The type of the server codec is Service[Array[Byte], Array[Byte]] and the client codecs are Service[ThriftClientRequest, Array[Byte]]. The service provided is that of a "transport" of thrift messages (requests and replies) according to the protocol chosen. This is why the client codecs need to have access to a thrift ProtocolFactory.

    These transports are used by the services produced by the finagle thrift codegenerator.

    val service: Service[ThriftClientRequest, Array[Byte]] = ClientBuilder()
      .hosts("foobar.com:123")
      .stack(Thrift.client)
      .build()
    
    // Wrap the raw Thrift transport in a Client decorator. The client
    // provides a convenient procedural interface for accessing the Thrift
    // server.
    val client = new Hello.ServiceToClient(service, protocolFactory)

    In this example, Hello is the thrift interface, and the inner class ServiceToClient is provided by the finagle thrift code generator.

    Definition Classes
    finagle
  • package thriftmux
    Definition Classes
    finagle
  • package toggle
    Definition Classes
    finagle
  • package tracing
    Definition Classes
    finagle
  • package opencensus
  • AnnotatingTracingFilter
  • Annotation
  • BroadcastTracer
  • BufferingTracer
  • ClientTracingFilter
  • ConsoleTracer
  • DefaultTracer
  • Flags
  • ForwardAnnotation
  • NullTracer
  • Record
  • ResourceTracingFilter
  • ServerTracingFilter
  • SpanId
  • Trace
  • TraceId
  • TraceId128
  • TraceInitializerFilter
  • TraceServiceName
  • TracelessFilter
  • Tracer
  • Tracing
  • TracingLogHandler
  • WireTracingFilter
  • enabled
  • traceId128Bit
  • package transport
    Definition Classes
    finagle
  • package tunable
    Definition Classes
    finagle
  • package util
    Definition Classes
    finagle
  • package zipkin
    Definition Classes
    finagle
  • package zookeeper
    Definition Classes
    finagle

package tracing

Ordering
  1. Alphabetic
Visibility
  1. Public
  2. Protected

Package Members

  1. package opencensus

Type Members

  1. sealed class AnnotatingTracingFilter[Req, Rep] extends SimpleFilter[Req, Rep]

    A generic filter that can be used for annotating the Server and Client side of a trace.

    A generic filter that can be used for annotating the Server and Client side of a trace. Finagle-specific trace information should live here.

  2. sealed abstract class Annotation extends AnyRef

    An ADT describing a tracing annotation.

    An ADT describing a tracing annotation. Prefer Tracing API to creating raw Annotation instances (especially, when used from Java).

  3. class BufferingTracer extends Tracer with Iterable[Record]

    A tracer that buffers each record in memory.

    A tracer that buffers each record in memory. These may then be iterated over.

  4. case class Flags(flags: Long) extends Product with Serializable

    Represents flags that can be passed along in request headers.

    Represents flags that can be passed along in request headers.

    flags

    Initial flag state. May be 0.

  5. class NullTracer extends Tracer

    A no-op Tracer.

    A no-op Tracer.

    Note

    supplying this tracer to a finagle client or server will not prevent trace information from being propagated to the next peer, but it will ensure that the client or server does not log any trace information about this host. If traces are being aggregated across your fleet, it will orphan subsequent spans.

  6. case class Record(traceId: TraceId, timestamp: Time, annotation: Annotation, duration: Option[Duration]) extends Product with Serializable

    Records information of interest to the tracing system.

    Records information of interest to the tracing system. For example when an event happened, the service name or ip addresses involved.

    traceId

    Which trace is this record a part of?

    timestamp

    When did the event happen?

    annotation

    What kind of information should we record?

    duration

    Did this event have a duration? For example: how long did a certain code block take to run

  7. final class SpanId extends Proxy with Serializable

    Defines trace identifiers.

    Defines trace identifiers. Span IDs name a particular (unique) span, while TraceIds contain a span ID as well as context (parentId and traceId).

  8. final case class TraceId(_traceId: Option[SpanId], _parentId: Option[SpanId], spanId: SpanId, _sampled: Option[Boolean], flags: Flags, traceIdHigh: Option[SpanId] = None, terminal: Boolean = false) extends Product with Serializable

    A trace id represents one particular trace for one request.

    A trace id represents one particular trace for one request.

    A request is composed of one or more spans, which are generally RPCs but may be other in-process activity. The TraceId for each span is a tuple of three ids:

    1. a shared id common to all spans in an overall request (trace id) 2. an id unique to this part of the request (span id) 3. an id for the parent request that caused this span (parent id)

    For example, when service M calls service N, they may have respective TraceIds like these:

               TRACE ID         SPAN ID           PARENT ID
    SERVICE M  e4bbb7c0f6a2ff07.a5f47e9fced314a2<:694eb2f05b8fd7d1
                      |                |
                      |                +-----------------+
                      |                                  |
                      v                                  v
    SERVICE N  e4bbb7c0f6a2ff07.263edc9b65773b08<:a5f47e9fced314a2

    Parent id and trace id are optional when constructing a TraceId because they are not present for the very first span in a request. In this case all three ids in the resulting TraceId are the same:

               TRACE ID         SPAN ID           PARENT ID
    SERVICE A  34429b04b6bbf478.34429b04b6bbf478<:34429b04b6bbf478
    _traceId

    The low 64bits of the id for this request.

    _parentId

    The id for the request one step up the service stack.

    spanId

    The id for this particular request

    _sampled

    Should we sample this request or not? True means sample, false means don't, none means we defer decision to someone further down in the stack.

    flags

    Flags relevant to this request. Could be things like debug mode on/off. The sampled flag could eventually be moved in here.

    traceIdHigh

    The high 64bits of the id for this request, when the id is 128bits.

    terminal

    Whether this trace id is terminal. Any attempts to override a terminal trace id will be ignored.

  9. case class TraceId128(low: Option[SpanId], high: Option[SpanId]) extends Product with Serializable
  10. class TraceInitializerFilter[Req, Rep] extends SimpleFilter[Req, Rep]

    The TraceInitializerFilter takes care of span lifecycle events.

    The TraceInitializerFilter takes care of span lifecycle events. It is always placed first in the service com.twitter.finagle.Filter chain (or last in the com.twitter.finagle.Stack) so that protocols with trace support will override the span resets, and still be properly reported here.

    Note

    This should be replaced by per-codec trace initializers that is capable of parsing trace information out of the codec.

  11. class TracelessFilter extends TypeAgnostic

    A filter to clear tracing information

  12. trait Tracer extends AnyRef

    Tracers record trace events.

  13. abstract class Tracing extends AnyRef

    This is a tracing system similar to Dapper:

    This is a tracing system similar to Dapper:

    “Dapper, a Large-Scale Distributed Systems Tracing Infrastructure”, Benjamin H. Sigelman, Luiz André Barroso, Mike Burrows, Pat Stephenson, Manoj Plakal, Donald Beaver, Saul Jaspan, Chandan Shanbhag, 2010.

    It is meant to be independent of whatever underlying RPC mechanism is being used, and it is up to the underlying codec to implement the transport.

    Trace (a singleton object) maintains the state of the tracing stack stored in com.twitter.finagle.context.Contexts. The current TraceId has a terminal flag, indicating whether it can be overridden with a different TraceId. Setting the current TraceId as terminal forces all future annotation to share that TraceId. When reporting, we report to all tracers in the list of Tracers.

    The Tracing API is structured in a way it's caller's responsibility to check if the current stack of tracers is actively tracing (Trace.isActivelyTracing) to avoid unnecessarily allocations.

    It's recommended to "capture" a Tracing instance while performing multiple tracing operations to minimize the number of com.twitter.finagle.context.Contexts lookups and increase throughput.

    // Performs six context lookups (two for isActivelyTracing, two for each record call).
    if (Trace.isActivelyTracing()) {
      Trace.record("foo")
      Trace.record("foo")
    }
    
    // Performs just two context lookups and captures the results in the `Trace` instance.
    val trace = Trace()
    if (trace.isActivelyTracing) {
      trace.record("foo")
      trace.record("bar")
    }
    Note

    Use Trace.getInstance() and Trace.newInstance() in Java.

  14. class TracingLogHandler extends Handler

    A logging Handler that sends log information via tracing

Value Members

  1. object AnnotatingTracingFilter
  2. object Annotation
  3. object BroadcastTracer
  4. object ClientTracingFilter

    Annotate the request with Client specific records (ClientSend, ClientRecv)

  5. object ConsoleTracer extends Tracer
  6. object DefaultTracer extends Tracer with Proxy
  7. object Flags extends Serializable
  8. object ForwardAnnotation

    Allow us to inject annotations into children trace contexts.

    Allow us to inject annotations into children trace contexts. Example, with dark traffic or retries we want to be able to tag the produced spans from each call (the light/dark calls, or each individual retry) with information that allows us to tie them together as a single logical item: a light request paired with a dark request, or an initial request and a series of retries. The problem lies in the fact that at the time we have the information about the relationship, the child trace context doesn't actually yet exist. In order to trace where it is needed, we need to have a hook into the trace context of these children requests which don't yet exist. We do this by placing annotations we want each child trace context to carry inside the local context and accessing them when the child trace context is realized through a stack module. The stack module will place a filter in the correct trace context, after the Trace Initialization Filter, which allows us to record the annotations in the proper place.

  9. object NullTracer extends NullTracer

    A singleton instance of a no-op NullTracer.

  10. object Record extends Serializable
  11. object ResourceTracingFilter

    Annotate the low level resource utilization of traced requests such as the accumulated cpu time of executed continuations.

  12. object ServerTracingFilter

    Annotate the request with Server specific records (ServerRecv, ServerSend)

  13. object SpanId extends Serializable
  14. object Trace extends Tracing

    A singleton instance of Tracing (a facade-style API) that performs a number of Contexts lookups on each operation.

    A singleton instance of Tracing (a facade-style API) that performs a number of Contexts lookups on each operation. Prefer "capturing" a Tracing instance for batching lookups.

    See also

    Tracing

  15. object TraceId extends Serializable
  16. object TraceId128 extends Serializable
  17. object TraceInitializerFilter
  18. object TraceServiceName

    Exposes an API for setting the global service name for this finagle process which is used to identify traces that belong to the respective process.

  19. object Tracer
  20. object Tracing
  21. object WireTracingFilter

    Annotate the request events directly before/after sending data on the wire (WireSend, WireRecv)

  22. object enabled extends GlobalFlag[Boolean]
  23. object traceId128Bit extends GlobalFlag[Boolean]

Ungrouped