Gerenciamento de recursos do Python

A biblioteca de gerenciamento de recursos do Python fornece uma maneira de desenvolver e expor funcionalidades de aplicativos com base em sinalizadores de recursos. Depois que um novo recurso é desenvolvido, muitos aplicativos têm requisitos especiais, como quando o recurso deve ser habilitado e sob quais condições. Esta biblioteca fornece uma maneira de definir esses relacionamentos e também se integra a padrões comuns de código Python para possibilitar a exposição desses recursos.

Os sinalizadores de recursos permitem que aplicativos Python ativem ou desativem recursos dinamicamente. Os desenvolvedores podem usar sinalizadores de recursos em casos de uso simples, como instruções condicionais.

Aqui estão alguns dos benefícios de usar a biblioteca de gerenciamento de recursos do Python:

• Uma convenção comum para o gerenciamento de recursos

• Baixa barreira de entrada

  • Suporta configuração de sinalizadores de recursos JSON

• Gerenciamento do ciclo de vida dos sinalizadores de recursos

  • Os valores de configuração podem ser alterados em tempo real; sinalizadores de recurso podem ser consistentes em toda a solicitação

• Abordamos cenários simples e complexos

  • Ative/desative recursos por meio do arquivo de configuração declarativa
  • Avalie dinamicamente o estado do recurso com base na chamada ao servidor

  A biblioteca de gerenciamento de recursos do Python é de código aberto. Para obter mais informações, acesse o repositório do GitHub.

Sinalizadores de recursos

Os sinalizadores de recursos são compostos por duas partes, um nome e uma lista de filtros de recursos usados para ativar o recurso.

Filtros de recursos

Os filtros de recursos definem um cenário para quando um recurso deve ser habilitado. Quando um recurso é avaliado se ele está ativado ou desativado, sua lista de filtros de recursos é percorrida até que um dos filtros decida que o recurso deve ser habilitado. Nesse ponto, o recurso é considerado habilitado e a passagem pelos filtros de recursos é interrompida. Se nenhum filtro de recurso indicar que o recurso deve ser habilitado, ele será considerado desabilitado.

Por exemplo, um filtro de recurso do navegador Microsoft Edge pode ser projetado. Esse filtro de recursos ativaria quaisquer recursos a ele associados, desde que uma solicitação HTTP viesse do Microsoft Edge.

Configuração do sinalizador de recurso

Um dicionário Python é usado para definir sinalizadores de recursos. O dicionário é composto por nomes de recursos como chaves e objetos de sinalização de recursos como valores. O objeto de sinalizador de recurso é um dicionário que contém uma chave conditions, que por sua vez contém a chave client_filters. A chave client_filters é uma lista de filtros de recursos usados ​​para determinar se o recurso deve ser ativado.

Declaração do sinalizador de recurso

A biblioteca de gerenciamento de recursos suporta JSON como fonte de sinalizadores de recursos. Abaixo, temos um exemplo do formato usado para configurar sinalizadores de recursos em um arquivo JSON.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "FeatureT",
                "enabled": true
            },
            {
                "id": "FeatureU",
                "enabled": false
            },
            {
                "id": "FeatureV",
                "enabled": true,
                "conditions": {
                    "client_filters": [
                        {
                            "name": "Microsoft.TimeWindow",
                            "parameters": {
                                "Start": "Wed, 01 May 2019 13:59:59 GMT",
                                "End": "Mon, 01 Jul 2019 00:00:00 GMT"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

A seção feature_management do documento json é usada por convenção para carregar as configurações do sinalizador de recurso. A seção feature_flags é uma lista dos sinalizadores de recursos que são carregados na biblioteca. Na seção acima, vemos três recursos diferentes. Os recursos definem seus filtros de recursos usando a propriedade client_filters, dentro de conditions. Nos filtros de recurso de FeatureT, observamos que enabled é true sem filtros definidos, fazendo com que FeatureT sempre retorne true. FeatureU é o mesmo que FeatureT mas com enabled é false resultando na funcionalidade sempre retornando false. FeatureV especifica um filtro de recursos chamado Microsoft.TimeWindow. FeatureV é um exemplo de um filtro de recursos configurável. Podemos ver no exemplo que o filtro tem uma propriedade parameters. A propriedade parameters é utilizada para configurar o filtro. Nesse caso, os horários de início e término do recurso a ser ativo são configurados.

O esquema detalhado da seção feature_management pode ser encontrado aqui.

Avançado: o uso de dois pontos ':' é proibido em nomes de sinalizadores de recursos.

Declaração de ligado/desligado

O trecho de código a seguir demonstra uma maneira alternativa de definir um recurso que pode ser usado para recursos de ativação/desativação.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "FeatureT",
                "enabled": "true"
            },
            {
                "id": "FeatureX",
                "enabled": "false"
            }
        ]
    }
}

Tipo de Requisito

A propriedade requirement_type de um sinalizador de recurso é usada para determinar se os filtros devem usar a lógica Any ou All ao avaliar o estado de um recurso. Se requirement_type não for especificado, o valor padrão será Any.

• Any significa que apenas um filtro precisa ser avaliado como verdadeiro para que o recurso seja ativado.
• All significa que todos os filtros precisam ser avaliados como verdadeiros para que o recurso seja ativado.

Um requirement_type de All altera a transversal. Primeiro, se não houver filtros, o recurso será desabilitado. Em seguida, os filtros de recurso são percorridos até que um dos filtros decida que o recurso deve ser desabilitado. Se nenhum filtro indicar que o recurso deve ser desabilitado, ele será considerado habilitado.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "FeatureW",
                "enabled": "true",
                "conditions": {
                    "requirement_type": "All",
                    "client_filters": [
                        {
                            "name": "Microsoft.TimeWindow",
                            "parameters": {
                                "Start": "Wed, 01 May 2019 13:59:59 GMT",
                                "End": "Mon, 01 Jul 2019 00:00:00 GMT"
                            }
                        },
                        {
                            "name": "Percentage",
                            "parameters": {
                                "Value": "50"
                            }
                        }
                    ]
                }
            },
        ]
    }
}

No exemplo acima, FeatureW especifica um requirement_type de All, o que significa que todos os seus filtros devem ser avaliados como verdadeiros para que o recurso seja habilitado. Nesse caso, o recurso está habilitado para 50% dos usuários durante a janela de tempo especificada.

Consumo

A forma básica de gerenciamento de recursos é verificar se um sinalizador de recurso está habilitado e executar ações com base no resultado. Verificar o estado de um sinalizador de recurso é feito através do método is_enabled de FeatureManager.

…
feature_manager = FeatureManager(feature_flags)
…
if feature_manager.is_enabled("FeatureX"):
    # Do something

O feature_flags fornecido para FeatureManager pode ser o AzureAppConfigurationProvider ou um dicionário de sinalizadores de recursos.

Implementando um filtro de recurso

A criação de um filtro de recursos fornece uma maneira de habilitar recursos com base nos critérios definidos por você. Para implementar um filtro de recurso, a interface FeatureFilter deve ser implementada. FeatureFilter possui um único método chamado evaluate. Quando um recurso especifica que ele pode ser habilitado para um filtro de recurso, o método evaluate é chamado. Se evaluate retornar true, significa que o recurso deve ser habilitado.

O trecho de código a seguir demonstra como adicionar um filtro de recurso MyCustomFilter personalizado.

feature_manager = FeatureManager(feature_flags, feature_filters=[MyCustomFilter()])

Os filtros de recursos são registrados ao serem fornecidos à propriedade feature_filters ao criar FeatureManager. Se um filtro de recurso personalizado precisar de algum contexto, ele poderá ser passado ao ser chamado is_enabled usando kwargs.

Atributo de alias de filtro

Quando um filtro de recursos é registrado para um sinalizador de recurso, o nome do filtro é usado como alias por padrão.

O identificador do filtro de recursos pode ser substituído usando o @FeatureFilter.alias("MyFilter"). Um filtro de recurso pode ser decorado com esse atributo para declarar o nome que deve ser usado na configuração para referenciar esse filtro de recurso dentro de um sinalizador de recurso.

Filtros de recursos ausentes

Se um recurso estiver configurado para ser ativado para um filtro de recursos específico e esse filtro de recursos não estiver registrado, uma exceção ValueError é levantado quando a funcionalidade é avaliada.

Filtros de recurso internos

Existem dois filtros de recursos que acompanham o pacote FeatureManagement: TimeWindowFilter, e TargetingFilter.

Cada um dos filtros de recursos internos tem seus próprios parâmetros. Aqui está a lista de filtros de recursos junto com exemplos.

Microsoft.TimeWindow

O Microsoft.TimeWindow filtro fornece uma maneira de habilitar um recurso com base em uma janela de tempo.

• Se você especificar apenas um End valor, o recurso será considerado ativado até esse momento.
• Se você especificar apenas um valor Start, o recurso será considerado ativo em todos os momentos a partir desse momento.

{
    "id": "EnhancedPipeline",
    "enabled": true,
    "conditions": {
        "client_filters": [
            {
                "name": "Microsoft.TimeWindow",
                "parameters": {
                    "Start": "Sun, 01 Jun 2025 13:59:59 GMT",
                    "End": "Fri, 01 Aug 2025 00:00:00 GMT"
                }
            }
        ]
    }
}

Você pode configurar o filtro para aplicar uma janela de tempo de forma recorrente. Essa funcionalidade pode ser útil quando você precisa ativar um recurso durante um período de tráfego baixo ou alto de um dia ou determinados dias de uma semana. Para expandir uma janela de tempo individual para uma janela de tempo recorrente, use um Recurrence parâmetro para especificar uma regra de recorrência.

{
    "id": "EnhancedPipeline",
    "enabled": true,
    "conditions": {
        "client_filters": [
            {
                "name": "Microsoft.TimeWindow",
                "parameters": {
                    "Start": "Fri, 22 Mar 2024 20:00:00 GMT",
                    "End": "Sat, 23 Mar 2024 02:00:00 GMT",
                    "Recurrence": {
                        "Pattern": {
                            "Type": "Daily",
                            "Interval": 1
                        },
                        "Range": {
                            "Type": "NoEnd"
                        }
                    }
                }
            }
        ]
    }
}

As Recurrence configurações são compostas por duas partes:

• As Pattern configurações especificam a frequência com que a janela de tempo se repete.
• As Range configurações especificam por quanto tempo o padrão de recorrência se repete.

Padrão de recorrência

Há dois tipos de padrão de recorrência possíveis: Daily e Weekly. Por exemplo, uma janela de tempo pode se repetir todos os dias, a cada três dias, todas as segundas-feiras ou todas as outras sextas-feiras.

Dependendo do tipo, determinados campos das Pattern configurações são necessários, opcionais ou ignorados.

• Daily

  O padrão de recorrência diária faz com que a janela de tempo se repita com base em um número especificado de dias entre cada ocorrência.

  Propriedade	Relevância	Descrição
  Type	Obrigatório	O tipo de padrão de recorrência. Deve ser definido como Daily.
  Interval	Opcional	O número de dias entre cada ocorrência. O valor padrão é 1.

• Weekly

  O padrão de recorrência semanal faz com que a janela de tempo se repita no mesmo dia ou dias da semana. Mas você pode especificar o número de semanas entre cada conjunto de ocorrências.

  Propriedade	Relevância	Descrição
  Type	Obrigatório	O tipo de padrão de recorrência. Deve ser definido como Weekly.
  DaysOfWeek	Obrigatório	Os dias da semana em que o evento ocorre.
  Interval	Opcional	O número de semanas entre cada conjunto de ocorrências. O valor padrão é 1.
  FirstDayOfWeek	Opcional	O dia a ser usado como o primeiro dia da semana. O valor padrão é Sunday.

  O exemplo a seguir repete a janela de tempo a cada segunda e terça-feira:

  "Pattern": {
      "Type": "Weekly",
      "Interval": 2,
      "DaysOfWeek": ["Monday", "Tuesday"]
  }
  

Intervalo de recorrência

Há três tipos de intervalo de recorrência possíveis: NoEnd, EndDatee Numbered.

• NoEnd

  O intervalo NoEnd faz com que a recorrência ocorra indefinidamente.

  Propriedade	Relevância	Descrição
  Type	Obrigatório	O tipo de intervalo de recorrência. Deve ser definido como NoEnd.

• EndDate

  O intervalo EndDate faz com que a janela de tempo ocorra em todos os dias que se ajustem ao padrão aplicável até a data de término.

  Propriedade	Relevância	Descrição
  Type	Obrigatório	O tipo de intervalo de recorrência. Deve ser definido como EndDate.
  EndDate	Obrigatório	A data e a hora para parar de aplicar o padrão. Se a hora de início da última ocorrência cair antes da data de término, a hora de término dessa ocorrência poderá se estender além dela.

  No exemplo a seguir, a janela de tempo se repete todos os dias até a última ocorrência em 1º de abril de 2024.

  "Start": "Fri, 22 Mar 2024 18:00:00 GMT",
  "End": "Fri, 22 Mar 2024 20:00:00 GMT",
  "Recurrence":{
      "Pattern": {
          "Type": "Daily",
          "Interval": 1
      },
      "Range": {
          "Type": "EndDate",
          "EndDate": "Mon, 1 Apr 2024 20:00:00 GMT"
      }
  }
  

• Numbered

  O Numbered intervalo faz com que a janela de tempo ocorra um número especificado de vezes.

  Propriedade	Relevância	Descrição
  Type	Obrigatório	O tipo de intervalo de recorrência. Deve ser definido como Numbered.
  NumberOfOccurrences	Obrigatório	O número de ocorrências.

  No exemplo a seguir, a janela de tempo se repete na segunda e na terça-feira para um total de três ocorrências, que ocorrem nas seguintes datas:

  • Segunda-feira, 1º de abril
  • Terça-feira, 2 de abril
  • Segunda-feira, 8 de abril

  "Start": "Mon, 1 Apr 2024 18:00:00 GMT",
  "End": "Mon, 1 Apr 2024 20:00:00 GMT",
  "Recurrence":{
      "Pattern": {
          "Type": "Weekly",
          "Interval": 1,
          "DaysOfWeek": ["Monday", "Tuesday"]
      },
      "Range": {
          "Type": "Numbered",
          "NumberOfOccurrences": 3
      }
  }
  

Para criar uma regra de recorrência, você deve especificar ambas as PatternRange configurações. Qualquer tipo de padrão pode funcionar com qualquer tipo de intervalo.

Avançado: o deslocamento de fuso horário da propriedade Start é aplicado às configurações de recorrência.

Microsoft.Targeting

Esse filtro fornece a capacidade de habilitar um recurso para um público-alvo. Uma explicação detalhada do direcionamento é explicada na seção direcionamento abaixo. Os parâmetros de filtro incluem um objeto Audience que descreve usuários, grupos, usuários/grupos excluídos e um percentual padrão da base de usuários que deve ter acesso ao recurso. Cada objeto de grupo listado na seção Groups também deve especificar qual porcentagem dos membros do grupo deve ter acesso. Se um usuário for especificado na seção Exclusion, diretamente ou se o usuário estiver em um grupo excluído, o recurso será desabilitado. Caso contrário, se um usuário for especificado diretamente na seção Users ou se o usuário estiver no percentual incluído de qualquer uma das distribuições de grupo ou se o usuário se enquadrar no percentual de distribuição padrão, esse usuário terá o recurso habilitado.

"client_filters": [
    {
        "name": "Microsoft.Targeting",
        "parameters": {
            "Audience": {
                "Users": [
                    "Jeff",
                    "Alicia"
                ],
                "Groups": [
                    {
                        "Name": "Ring0",
                        "RolloutPercentage": 100
                    },
                    {
                        "Name": "Ring1",
                        "RolloutPercentage": 50
                    }
                ],
                "DefaultRolloutPercentage": 20,
                "Exclusion": {
                    "Users": [
                        "Ross"
                    ],
                    "Groups": [
                        "Ring2"
                    ]
                }
            }
        }
    }
]

Direcionamento

A segmentação é uma estratégia de gerenciamento de recursos que permite aos desenvolvedores implementar progressivamente novos recursos para sua base de usuários. A estratégia baseia-se no conceito de atingir um conjunto de usuários conhecido como público-alvo. Um público é composto por usuários, grupos específicos e uma porcentagem designada de toda a base de usuários. Os grupos incluídos na audiência podem ser divididos ainda mais em percentuais de seus membros totais.

As etapas a seguir demonstram um exemplo de uma distribuição progressiva para um novo recurso "Beta":

1. Os usuários individuais Júlio e Alice recebem acesso à versão beta.
2. Outro usuário, Mark, pede para aceitar e é incluído.
3. Vinte por cento de um grupo conhecido como usuários "Ring1" estão incluídos no Beta.
4. O número de usuários “Ring1” incluídos na versão beta é aumentado para 100%.
5. Cinco por cento da base de usuários está incluída na versão beta.
6. O percentual de distribuição é aumentado em até 100% e o recurso é completamente distribuído.

Esta estratégia para implantar um recurso é incorporada à biblioteca por meio do filtro de recursos Microsoft.Targeting incluso.

Direcionando um usuário

Um usuário pode ser especificado diretamente na chamada is_enabled ou uma TargetingContext pode ser usada para especificar o usuário e o grupo opcional.

# Directly specifying the user
result = is_enabled(feature_flags, "test_user")

# Using a TargetingContext
result = is_enabled(feature_flags, TargetingContext(user_id="test_user", groups=["Ring1"]))

Exclusão de direcionamento

Ao definir um público-alvo, usuários e grupos podem ser excluídos dele. As exclusões são úteis quando um recurso está sendo implementado para um grupo de usuários, mas alguns usuários ou grupos precisam ser excluídos dessa implementação. A exclusão é definida adicionando uma lista de usuários e grupos à propriedade Exclusion do público-alvo.

"Audience": {
    "Users": [
        "Jeff",
        "Alicia"
    ],
    "Groups": [
        {
            "Name": "Ring0",
            "RolloutPercentage": 100
        }
    ],
    "DefaultRolloutPercentage": 0,
    "Exclusion": {
        "Users": [
            "Mark"
        ]
    }
}

No exemplo acima, o recurso está habilitado para usuários chamados Jeff e Alicia. Ele também está habilitado para usuários no grupo chamado Ring0. No entanto, se o usuário for chamado Mark, o recurso será desabilitado, independentemente de estar no grupo Ring0 ou não. As exclusões têm prioridade sobre o restante do filtro de direcionamento.

Variantes

Quando novos recursos são adicionados a um aplicativo, pode chegar um momento em que um recurso tem várias opções de design propostas diferentes. Uma solução comum para decidir sobre um design é alguma forma de teste A/B. Os testes A/B envolvem fornecer uma versão diferente do recurso para diferentes segmentos da base de usuários e escolher uma versão com base na interação do usuário. Nesta biblioteca, essa funcionalidade é habilitada por meio da representação de diferentes configurações de um recurso com variantes.

As variantes permitem que um sinalizador de recurso se torne mais do que um sinalizador simples de ativação/desativação. Uma variante representa um valor de um sinalizador de recurso que pode ser uma cadeia de caracteres, um número, um booliano ou até mesmo um objeto de configuração. Um sinalizador de recurso que declara variantes deve definir em quais circunstâncias cada variante deve ser usada, o que é abordado em maior detalhe na seção Alocação de variantes.

class Variant:
    def __init__(self, name: str, configuration: Any):
        self._name = name
        self._configuration = configuration

    @property
    def name(self) -> str:
        """
        The name of the variant.
        :rtype: str
        """
        return self._name

    @property
    def configuration(self) -> Any:
        """
        The configuration of the variant.
        :rtype: Any
        """
        return self._configuration

Obtendo variantes

Para cada recurso, uma variante pode ser recuperada usando o método FeatureManagerdo get_variant.

…
variant = print(feature_manager.get_variant("TestVariants", TargetingContext(user_id="Adam"))

variantConfiguration = variant.configuration;

// Do something with the resulting variant and its configuration

A variante retornada depende do usuário que está sendo avaliado no momento e essas informações são obtidas de uma instância de TargetingContext.

Declaração do sinalizador de recurso variante

Em comparação com os indicadores de recursos normais, os indicadores de recursos variantes possuem duas propriedades adicionais: variants e allocation. A propriedade variants é uma matriz que contém as variantes definidas para esse recurso. A propriedade allocation define como essas variantes devem ser alocadas para o recurso. Assim como na declaração de sinalizadores de recursos normais, você pode configurar sinalizadores de recursos variantes em um arquivo JSON. Aqui está um exemplo de um sinalizador de recurso variante.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "MyVariantFeatureFlag",
                "enabled": true,
                "allocation": {
                    "default_when_enabled": "Small",
                    "group": [
                        {
                            "variant": "Big",
                            "groups": [
                                "Ring1"
                            ]
                        }
                    ]
                },
                "variants": [
                    { 
                        "name": "Big"
                    },  
                    { 
                        "name": "Small"
                    } 
                ]
            }
        ]
    }
}

Definindo variantes

Cada variante tem duas propriedades: um nome e uma configuração. O nome é usado para se referir a uma variante específica e a configuração é o valor dessa variante. A configuração pode ser definida usando a propriedade configuration_value. configuration_value é uma configuração embutida que pode ser uma string, um número, um valor booleano ou um objeto de configuração. Se configuration_value não for especificado, a propriedade Configuration da variante retornada será None.

Uma lista de todas as variantes possíveis é definida para cada recurso na propriedade variants.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "MyVariantFeatureFlag",
                "variants": [
                    { 
                        "name": "Big", 
                        "configuration_value": {
                            "Size": 500
                        }
                    },  
                    { 
                        "name": "Small", 
                        "configuration_value": {
                            "Size": 300
                        }
                    } 
                ]
            }
        ]
    }
}

Alocando variantes

O processo de alocação das variantes de um recurso é determinado pela propriedade allocation do recurso.

"allocation": { 
    "default_when_enabled": "Small", 
    "default_when_disabled": "Small",  
    "user": [ 
        { 
            "variant": "Big", 
            "users": [ 
                "Marsha" 
            ] 
        } 
    ], 
    "group": [ 
        { 
            "variant": "Big", 
            "groups": [ 
                "Ring1" 
            ] 
        } 
    ],
    "percentile": [ 
        { 
            "variant": "Big", 
            "from": 0, 
            "to": 10 
        } 
    ], 
    "seed": "13973240" 
},
"variants": [
    { 
        "name": "Big", 
        "configuration_value": "500px"
    },  
    { 
        "name": "Small", 
        "configuration_value": "300px"
    } 
]

A configuração allocation de um recurso tem as seguintes propriedades:

Se o recurso não estiver ativado, o gerenciador de recursos atribuirá a variante marcada como default_when_disabled para o usuário atual, que é Small nesse caso.

Se o recurso estiver ativado, o gerenciador de recursos verifica as alocações user, group, e percentile nessa ordem para atribuir uma variante. Para este exemplo específico, se o usuário que está sendo avaliado for nomeado Marsha, no grupo nomeado Ring1, ou se o usuário estiver entre o percentil 0 e 10, a variante especificada será atribuída ao usuário. Nesse caso, todos os usuários atribuídos retornariam a variante Big. Se nenhuma dessas alocações corresponder, o usuário recebe a variante default_when_enabled, que é Small.

A lógica de alocação é semelhante ao filtro de recursos Microsoft.Targeting, mas há alguns parâmetros presentes no direcionamento que não estão em alocação e vice-versa. Os resultados de direcionamento e alocação não estão relacionados.

Substituindo o estado habilitado com uma variante

Você pode usar variantes para substituir o estado habilitado de um sinalizador de recurso. A substituição dá às variantes a oportunidade de estender a avaliação de um sinalizador de recurso. Ao chamar is_enabled em um sinalizador com variantes, o gerenciador de recursos verificará se a variante atribuída ao usuário atual está configurada para substituir o resultado. A substituição é feita usando a propriedade de variante opcional status_override. Por padrão, essa propriedade é definida como None, o que significa que a variante não afeta se o sinalizador é considerado habilitado ou desabilitado. A configuração status_override para Enabled permite que a variante, quando escolhida, substitua um sinalizador a ser habilitado. A configuração status_override para Disabled fornece a funcionalidade oposta, desabilitando o sinalizador quando a variante for escolhida. Um recurso com um estado enabled de false não pode ser substituído.

Se você estiver usando um sinalizador de recurso com variantes binárias, a variante status_override pode ser útil. Isso permite que você continue usando APIs como is_enabled em seu aplicativo, tudo isso enquanto se beneficia dos novos recursos que acompanham as variantes, como alocação de percentil e semente.

{
    "id": "MyVariantFeatureFlag",
    "enabled": true,
    "allocation": {
        "percentile": [
            {
                "variant": "On",
                "from": 10,
                "to": 20
            }
        ],
        "default_when_enabled":  "Off",
        "seed": "Enhanced-Feature-Group"
    },
    "variants": [
        {
            "name": "On"
        },
        {
            "name": "Off",
            "status_override": "Disabled"
        }
    ]
}

No exemplo acima, o recurso está sempre habilitado. Se o usuário atual estiver no intervalo de percentil calculado de 10 a 20, a variante On será retornada. Caso contrário, a variante Off será retornada e, como status_override é igual a Disabled, o recurso agora será considerado desabilitado.

Telemetria

Quando uma alteração de sinalizador de recurso é implantada, geralmente é importante analisar seu efeito em um aplicativo. Por exemplo, aqui estão algumas perguntas que podem surgir:

• Meus sinalizadores estão habilitados/desabilitados conforme o esperado?
• Os usuários direcionados estão recebendo acesso a um determinado recurso conforme o esperado?
• Qual variante um usuário específico vê?

Esses tipos de perguntas podem ser respondidas por meio da emissão e análise de eventos de avaliação do sinalizador de recurso. Esta biblioteca habilita opcionalmente AzureMonitor produzir telemetria de rastreamento durante a avaliação de sinalizadores de recursos via OpenTelemetry.

Habilitando a telemetria

Por padrão, os sinalizadores de recursos não têm telemetria emitida. Para publicar telemetria para um determinado sinalizador de recurso, o sinalizador MUST declara que está habilitado para emissão de telemetria.

Para sinalizadores de recursos definidos em JSON, a ativação é feita usando a propriedade telemetry.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "MyFeatureFlag",
                "enabled": true,
                "telemetry": {
                    "enabled": true
                }
            }
        ]
    }
}

O trecho acima define um sinalizador de recurso chamado MyFeatureFlag que está habilitado para telemetria. A propriedade do objeto telemetry é enabled definida como true. O valor da propriedade enabled deve ser true para publicar telemetria para o sinalizador.

A seção telemetry de um sinalizador de recurso tem as seguintes propriedades:

Além disso, ao criar FeatureManager, é necessário registrar uma função de retorno de chamada para lidar com eventos de telemetria. Esse retorno de chamada é chamado sempre que um sinalizador de recurso é avaliado e a telemetria está habilitada para esse sinalizador.

feature_manager = FeatureManager(feature_flags, on_feature_evaluated=publish_telemetry)

Application Insights Telemetry

A biblioteca de gerenciamento de recursos fornece um publicador de telemetria integrado que envia dados de avaliação de sinalizadores de recursos para Application Insights. Para habilitar o Application Insights, a biblioteca de gerenciamento de recursos pode ser instalada com o Azure Monitor através do seguinte link: pip install FeatureManagement[AzureMonitor]. Este comando instala o pacote azure-monitor-events-extension, que é usado para formatar a telemetria para o Application Insights usando o OpenTelemetry.

from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor(
        connection_string="InstrumentationKey=00000000-0000-0000-0000-000000000000"
    )

Publicação de telemetria personalizada

Como o retorno de chamada de telemetria é uma função, ele pode ser personalizado para publicar telemetria em qualquer destino desejado. Por exemplo, a telemetria pode ser publicada em um serviço de registro, um banco de dados ou um serviço de telemetria personalizado.

Quando um sinalizador de recurso é avaliado e a telemetria é ativada, o gerenciador de recursos chama o retorno de chamada de telemetria com um parâmetro EvaluationEvent. EvaluationEvent contém as seguintes propriedades:

Próximas etapas

Para aprender como usar sinalizadores de recursos em seus aplicativos, continue com os seguintes guias de início rápido.

Para aprender a usar filtros de recursos, continue com os tutoriais a seguir.