Configuration¶

fedora-messaging can be configured with the /etc/fedora-messaging/config.toml file or by setting the FEDORA_MESSAGING_CONF environment variable to the path of the configuration file.

Each configuration option has a default value.

Table of Configuration Options

Generic Options
Publisher Options
Consumer Options
- queues
- bindings
- callback
- consumer_config
- qos

A complete example TOML configuration:

# A sample configuration for fedora-messaging. This file is in the TOML format.
amqp_url = "amqp://"
callback = "fedora_messaging.example:printer"
passive_declares = false
publish_exchange = "amq.topic"
topic_prefix = ""

[tls]
ca_cert = "/etc/fedora-messaging/cacert.pem"
keyfile = "/etc/fedora-messaging/fedora-key.pem"
certfile = "/etc/fedora-messaging/fedora-cert.pem"

[client_properties]
app = "Example Application"

# If the exchange or queue name  has a "." in it, use quotes as seen here.
[exchanges."amq.topic"]
type = "topic"
durable = true
auto_delete = false
arguments = {}

[queues.my_queue]
durable = true
auto_delete = false
exclusive = false
arguments = {}

# Note the double brackets below. To add another binding, add another
# [[bindings]] section. To use multiple routing keys, just expand the list here.
[[bindings]]
queue = "my_queue"
exchange = "amq.topic"
routing_keys = ["#"]

[consumer_config]
example_key = "for my consumer"

[qos]
prefetch_size = 0
prefetch_count = 25

[log_config]
version = 1
disable_existing_loggers = true

[log_config.formatters.simple]
format = "[%(levelname)s %(name)s] %(message)s"

[log_config.handlers.console]
class = "logging.StreamHandler"
formatter = "simple"
stream = "ext://sys.stdout"

[log_config.loggers.fedora_messaging]
level = "INFO"
propagate = false
handlers = ["console"]

# Twisted is the asynchronous framework that manages the TCP/TLS connection, as well
# as the consumer event loop. When debugging you may want to lower this log level.
[log_config.loggers.twisted]
level = "INFO"
propagate = false
handlers = ["console"]

# Pika is the underlying AMQP client library. When debugging you may want to
# lower this log level.
[log_config.loggers.pika]
level = "WARNING"
propagate = false
handlers = ["console"]

[log_config.root]
level = "ERROR"
handlers = ["console"]

Generic Options ¶

These options apply to both consumers and publishers.

amqp_url ¶

The AMQP broker to connect to. This URL should be in the format described by the pika.connection.URLParameters documentation. This defaults to 'amqp://?connection_attempts=3&retry_delay=5.

Note

When using the Twisted consumer API, which the CLI does by default, any connection-related setting won’t apply as Twisted manages the TCP/TLS connection.

passive_declares ¶

A boolean to specify if queues and exchanges should be declared passively (i.e checked, but not actually created on the server). Defaults to False.

tls ¶

A dictionary of the TLS settings to use when connecting to the AMQP broker. The default is:

{
    'ca_cert': '/etc/pki/tls/certs/ca-bundle.crt',
    'keyfile': None,
    'certfile': None,
}

The value of ca_cert should be the path to a bundle of CA certificates used to validate the certificate presented by the server. The ‘keyfile’ and ‘certfile’ values should be to the client key and client certificate to use when authenticating with the broker.

Note

The broker URL must use the amqps scheme. It is also possible to provide these setting via the amqp_url setting using a URL-encoded JSON object. This setting is provided as a convenient way to avoid that.

client_properties ¶

A dictionary that describes the client to the AMQP broker. This makes it easy to identify the application using a connection. The dictionary can contain arbitrary string keys and values. The default is:

{
    'app': 'Unknown',
    'product': 'Fedora Messaging with Pika',
    'information': 'https://fedora-messaging.readthedocs.io/en/stable/',
    'version': 'fedora_messaging-<version> with pika-<version>',
}

Apps should set the app along with any additional keys they feel will help administrators when debugging application connections. At a minimum, the recommended fields are:

app_url: The value of this key should be a URL to the upstream project for the client.
app_contacts_email: One or more emails of maintainers to contact with questions (if, for example, a client is misbehaving, or a service disruption is about to occur).

Do not use the product, information, and version keys as these will be set automatically.

exchanges ¶

A dictionary of exchanges that should be present in the broker. Each key should be an exchange name, and the value should be a dictionary with the exchange’s configuration. Options are:

type - the type of exchange to create.
durable - whether or not the exchange should survive a broker restart.
auto_delete - whether or not the exchange should be deleted once no queues are bound to it.
arguments - dictionary of arbitrary keyword arguments for the exchange, which depends on the broker in use and its extensions.

For example:

{
    'my_exchange': {
        'type': 'fanout',
        'durable': True,
        'auto_delete': False,
        'arguments': {},
    },
}

The default is to ensure the ‘amq.topic’ topic exchange exists which should be sufficient for most use cases.

log_config ¶

A dictionary describing the logging configuration to use, in a format accepted by logging.config.dictConfig().

Note

Logging is only configured for consumers, not for producers.

Publisher Options ¶

The following configuration options are publisher-related.

publish_exchange ¶

A string that identifies the exchange to publish to. The default is amq.topic.

topic_prefix ¶

A string that will be prepended to topics on sent messages. This is useful to migrate from fedmsg, but should not be used otherwise. The default is an empty string.

publish_priority ¶

A number that will be set as the priority for the messages. The range of possible priorities depends on the x-max-priority argument of the destination queue, as described in RabbitMQ’s priority documentation. The default is None, which RabbitMQ will interpret as zero.

Consumer Options ¶

The following configuration options are consumer-related.

queues ¶

A dictionary of queues that should be present in the broker. Each key should be a queue name, and the value should be a dictionary with the queue’s configuration. Options are:

durable - whether or not the queue should survive a broker restart. This is set to False for the default queue.
auto_delete - whether or not the queue should be deleted once the consumer disconnects. This is set to True for the default queue.
exclusive - whether or not the queue is exclusive to the current connection. This is set to False for the default queue.
arguments - dictionary of arbitrary keyword arguments for the queue, which depends on the broker in use and its extensions. This is set to {} for the default queue

For example:

{
    'my_queue': {
        'durable': True,
        'auto_delete': True,
        'exclusive': False,
        'arguments': {},
    },
}

bindings ¶

A list of dictionaries that define queue bindings to exchanges that consumers will subscribe to. The queue key is the queue’s name. The exchange key should be the exchange name and the routing_keys key should be a list of routing keys. For example:

[
    {
        'queue': 'my_queue',
        'exchange': 'amq.topic',
        'routing_keys': ['topic1', 'topic2.#'],
    },
]

This would create two bindings for the my_queue queue, both to the amq.topic exchange. Consumers will consume from both queues.

callback ¶

The Python path of the callback. This should be in the format <module>:<object>. For example, if the callback was called “my_callback” and was located in the “my_module” module of the “my_package” package, the path would be defined as my_package.my_module:my_callback. The default is None.

Consult the Consumers documentation for details on implementing a callback.

consumer_config ¶

A dictionary for the consumer to use as configuration. The consumer should access this key in its callback for any configuration it needs. Defaults to an empty dictionary. If, for example, this dictionary contains the print_messages key, the callback can access this configuration with:

from fedora_messaging import config

def callback(message):
    if config.conf["consumer_config"]["print_messages"]:
        print(message)

qos ¶

The quality of service settings to use for consumers. This setting is a dictionary with two keys. prefetch_count specifies the number of messages to pre-fetch from the server. Pre-fetching messages improves performance by reducing the amount of back-and-forth between client and server. The downside is if the consumer encounters an unexpected problem, messages won’t be returned to the queue and sent to a different consumer until the consumer times out. prefetch_size limits the size of pre-fetched messages (in bytes), with 0 meaning there is no limit. The default settings are:

{
    'prefetch_count': 10,
    'prefetch_size': 0,
}

Configuration¶

Generic Options ¶

amqp_url ¶

passive_declares ¶

tls ¶

client_properties ¶

exchanges ¶

log_config ¶

Publisher Options ¶

publish_exchange ¶

topic_prefix ¶

publish_priority ¶

Consumer Options ¶

queues ¶

bindings ¶

callback ¶

consumer_config ¶

qos ¶

Fedora Messaging

Navigation

Related Topics